[xml/sgml-commit] r1147 - in /packages/sgml-base-doc: ./ trunk/ trunk/debian/
dleidert-guest at users.alioth.debian.org
dleidert-guest at users.alioth.debian.org
Tue Sep 2 12:01:04 UTC 2008
Author: dleidert-guest
Date: Tue Sep 2 12:01:03 2008
New Revision: 1147
URL: http://svn.debian.org/wsvn/debian-xml-sgml/?sc=1&rev=1147
Log:
[svn-inject] Installing original source of sgml-base-doc
Added:
packages/sgml-base-doc/
packages/sgml-base-doc/trunk/
packages/sgml-base-doc/trunk/EXPLANATIONS.lsb
packages/sgml-base-doc/trunk/Makefile
packages/sgml-base-doc/trunk/POLICY
packages/sgml-base-doc/trunk/README
packages/sgml-base-doc/trunk/RECOMMENDATIONS.fhs
packages/sgml-base-doc/trunk/RECOMMENDATIONS.lsb
packages/sgml-base-doc/trunk/debian/
packages/sgml-base-doc/trunk/debian/TODO
packages/sgml-base-doc/trunk/debian/changelog
packages/sgml-base-doc/trunk/debian/compat
packages/sgml-base-doc/trunk/debian/control
packages/sgml-base-doc/trunk/debian/copyright
packages/sgml-base-doc/trunk/debian/rules (with props)
packages/sgml-base-doc/trunk/debian/sgml-base-doc.README.Debian
packages/sgml-base-doc/trunk/debian/sgml-base-doc.doc-base
packages/sgml-base-doc/trunk/debian/sgml-base-doc.docs
packages/sgml-base-doc/trunk/sgml_layout.sgml
Added: packages/sgml-base-doc/trunk/EXPLANATIONS.lsb
URL: http://svn.debian.org/wsvn/debian-xml-sgml/packages/sgml-base-doc/trunk/EXPLANATIONS.lsb?rev=1147&op=file
==============================================================================
--- packages/sgml-base-doc/trunk/EXPLANATIONS.lsb (added)
+++ packages/sgml-base-doc/trunk/EXPLANATIONS.lsb Tue Sep 2 12:01:03 2008
@@ -1,0 +1,232 @@
+Explanantions of the recommendations to LSB
+-------------------------------------------
+
+Introduction
+------------
+
+This document explains the choices that have been made for the
+recommendations to LSB about DocBook. This is presented in a separate
+document to leave the draft concentrate only on the "what?" and not on
+the "why?"
+
+There are hundreds of man-hours behind those recommendations. They really
+costed blood, sweat and tears. Each line was discussed many times and
+the global architecture changed quite often. We really tried to hear
+what everyone add to say. So we would like to encourage LSB in being
+very careful if they want to modify them.
+
+The general philosophy was to keep the "historical" choices everywhere
+it had no consequences, and the "best" technical choice wherever it was
+interesting. We have attempted to design a very simple but also powerful
+architecture, in full respect of the FHS (File system Hierarchy Standard).
+
+Another general principal of design was to think to the user, not to
+the theory. There were many models that would have been much more
+intellectually satisfactory - but they were all too complex for
+everyday's use.
+
+Definitions
+-----------
+
+Why those definitions? Because we realized we were speaking about
+different things with the same words. An example is "SGML application":
+it can both refer to a specific DTD, or to a computer program meant to
+process some SGML or XML document, both definitions being perfectly
+correct. To avoid any potential confusion, we just chose the one
+we needed.
+
+Some definitions like "helper", "backend" and "frontend" are not even
+necessary to read the rest of the document. We left them because we
+needed them to provide a reference implementation.
+
+
+R001 - SGML Directory layout
+----------------------------
+
+Some existing projects were putting files in /usr/lib/sgml, some other
+in /usr/local/share/sgml. Those files are not libraries nor local to a
+system, so we chose /usr/share/sgml.
+
+Some projects used to put centralized catalogs at the same place as the
+other catalogs. Since they can be seen as system configuration files,
+it was locgical to centralize them in /etc.
+
+One very hard question was: should we separe sgml from xml?
+The relationship between one and the other is very strong, so we chose
+to keep them at the same place in the directory tree. This allows,
+for example, to have all docbook stuff, both sgml and xml, at the very
+same place, which is obviously practical.
+
+While /usr/share/sgml does not explicitely reflect this, we found that
+it was still better than /usr/share/markup (what about TeX then?),
+than /usr/share/ml or than other proposals.
+
+Why having fixed file paths while you could have got them from some
+configuration variables, autoconf mechanisms, etc? First because it's
+simpler: we wanted a very strong standard, given that the tools may
+still use such configuration variables or autoconf mechanisms to adapt
+to non-LSB platforms. We considered that a standard that does not specify
+enough is somehow encouraging the most bizarre variations.
+
+We chose a dtd-and-package-oriented architecture, instead of a
+file-type-oriented structure.
+
+This was probably the most controversial issue. The "natural" proposal for
+SGML and XML specialists is to have the FPIs map almost letter-per-letter
+in the directory names. However, this approach does not take profit of
+the catalogs mechanism that allow to map FPIs into file paths.
+
+A file-type-oriented architecture would have lead things like:
+
+/usr/share/sgml/USA-DOD/DTD_Table_Model_951010/EN/
+/usr/share/sgml/OASIS/DTD_DocBook_V3.1/EN/
+/usr/share/sgml/OASIS/ELEMENTS_DocBook_Information_Pool_V3.1/EN/
+/usr/share/sgml/OASIS/ELEMENTS_DocBook_Document_Hierarchy_V3.1/EN/
+/usr/share/sgml/OASIS/ENTITIES_DocBook_Additional_General_Entities_V3.1/EN/
+/usr/share/sgml/OASIS/ENTITIES_DocBook_Notations_V3.1/EN/
+/usr/share/sgml/OASIS/ENTITIES_DocBook_Character_Entities_V3.1/EN/
+
+or something more far away from the FPIs like:
+
+/usr/share/sgml/sgml-dtd/hal/docbook/2.4/
+/usr/share/sgml/sgml-dtd/davenport/docbook/3.0/
+/usr/share/sgml/sgml-dtd/davenport/docbook/3.0/
+/usr/share/sgml/sgml-dtd/oasis/docbook/3.1/
+/usr/share/sgml/xml-dtd/oasis/docbook/4.0/
+/usr/share/sgml/dssl-stylesheets/nwalsh/docbook/3.1/
+/usr/share/sgml/xsl-stylesheets/nwalsh/docbook/4.0/
+/usr/share/sgml/sgml-dtd/ietf/html/2.0/
+/usr/share/sgml/sgml-dtd/w3c/html/3.2/
+
+but in all the case, the files would have been spread according to their
+file types in distant directories. We would probably have had entities
+somewhere, stylesheets somewhere else, dtds in a third place, and sgml
+declarations in a fourth place. This would certainly have broke some
+relative paths, and required more packaging work.
+
+The user does not think in terms of file types, whereas SGML specialists
+do. The user only thinks "I want to do some MathML" or "I want to do some
+XHTML" or "I want to do some TEI". This is why the basic unit is the DTD.
+This DTD-centered approach does not mean that first level directories are
+for DTDs. It just means that they hold everything related to a given DTD:
+stylesheets, enterprise-wide customizations, etc...
+
+
+R002 - DocBook Directory layout
+-------------------------------
+
+Maybe the document seems confused because it mixes recommendantions
+for SGML and XML with recommendations for DocBook. It would somehow
+have been good to separate it into two documents. On the other hand,
+this allowed to think in very practical terms.
+
+There is only one lower level of directories. The directory names are
+vaguely defined as holding one "package". One advantage is that the
+relation to any RPM or DEB package is very close. The other advantage
+is that we have a very flat tree, thus easing both hacking, packaging
+and maintenance by system administrators.
+
+The lower level directories are version-numbered. This unusual naming
+scheme is intended to permit documents that are written using several
+versions of the same DTD to coexist on the same system.
+
+
+R003 - Open Catalog usage for SGML
+----------------------------------
+
+Why focusing so much on catalogs in these recommendations? Because
+they are the key to your directory structure and give a strong working
+infrastructure that every SGML or XML tool can count on.
+
+Open catalogs have very often been resented because they lead to problems
+like conflicting SGMLDECLs. However, those problems do not appear if
+you use them carefully. One of the keys is to avoid putting everything
+in the same bag, and to have centralized catalogs that are specific to
+a given DTD.
+
+The fact that they are DTD-specific has a number of advantages:
+ - avoid SGMLDECL conflicts without assuming DTDDECL or
+ DELEGATE support, which many tools still not support yet
+ - avoid duplicate FPI declarations
+ - allow to point to the right version of a given DTD
+ and to the corresponding entities and style sheets from only one place
+
+When splitting your CATALOG pointers in one file per DTD, you also somehow
+lose a global vision on all the catalogs that are installed on your
+system. This is why we have introduced the super-catalog, pointing to all
+the centralized catalogs on your system. It eases a lot scripting issues.
+
+The super catalog may be used as a default centralized catalog, for
+example when the DTD is not known, however it can't be guaranteed that
+there won't be any declaration conflicts if an application chooses to
+use this functionality.
+
+OASIS says that all the catalogs should be named "CATALOG" or
+"catalog". This was impossible to respect in /etc/sgml where you will
+have the centralized catalogs, because many files cannot hold the same
+name. Somehow it does not break those directives that much, because all
+the ordinary catalogs on your system would still be named "catalog".
+
+We also choose to specify "catalog" rathen than "CATALOG", while OASIS
+leaves the choice. We considered that we should encourage one of both
+versions, whichever it should be, because it made live simpler for
+everyone (scripts, maintainers, packagers, tools authors, ...). In this
+respect, LSB implementations could be considered as conformant to OASIS,
+while the contrary would not be true.
+
+
+R004 - Open Catalog usage for DocBook
+-------------------------------------
+
+Directories like the ones holding Jade's or OpenJade's declarations and
+the ISO entities are on top level because they are not specific to any
+given DTD and can be used by two or more of them.
+
+Of course one may argue that Jade's or OpenJade's declarations contain the
+document type definition of what DSSSL is. But again what is important
+is the usage, not the formal definition, so it has no reason to go to
+a dsssl/ directory (which would also encourage packagers to put the
+stylesheets in, away from their dtd, which is not what we want).
+
+
+R005 - Configuration files
+--------------------------
+
+This recommendation is voluntarily vague, to ease as much as possible the
+possibility to create SGML applications with not creativity restrictions
+with respect to configuration files - the catalog layout solves anyhow
+one of their major problems: find the files.
+
+
+R006 - Iso-entities
+-------------------
+
+So far, the most confusion has been with the file names holding these
+very basic character entities. We have seen the following naming schemes:
+ ISOamsa ISOamsb ...
+ ISOamsa.ent ISOamsb.ent ...
+ iso-amsa iso-amsb ...
+ iso-amsa.gml iso-amsb.gml ...
+ etc...
+
+There was a similar confusion for the Formal public identifiers describing
+these files. We have seen the following naming schemes:
+
+ "ISO 8879:1986//ENTITIES Added Math Symbols: Arrow Relations//EN"
+ "ISO 8879-1986//ENTITIES Added Math Symbols: Arrow Relations//EN"
+
+Again, we chose to avoid deciding not to decide. We had a lot of feedback
+from users suffering from this indecision. Even if technical workarounds
+exist, we would like to encourage one of these forms to emerge.
+
+R007 - Packages
+---------------
+
+We are very far from providing inter-distribution compatibility at the
+package level, and it is likely that someone will get broken dependencies
+if he/she mixes packages coming from different distributions.
+
+This document will not try to fix package names nor proposed dependency
+declarations for DocBook distributions. We however wanted to point out
+a problem that may be encountered when packaging SGML or XML: the package
+numbering scheme.
Added: packages/sgml-base-doc/trunk/Makefile
URL: http://svn.debian.org/wsvn/debian-xml-sgml/packages/sgml-base-doc/trunk/Makefile?rev=1147&op=file
==============================================================================
--- packages/sgml-base-doc/trunk/Makefile (added)
+++ packages/sgml-base-doc/trunk/Makefile Tue Sep 2 12:01:03 2008
@@ -1,0 +1,30 @@
+## ----------------------------------------------------------------------
+## Makefile : makefile for sgml-base-doc
+## ----------------------------------------------------------------------
+
+## ----------------------------------------------------------------------
+## Document definitions
+doc_name := sgml_layout
+doc_sgml := $(doc_name).sgml
+doc_html := $(doc_name).html
+doc_pdf := $(doc_name).pdf
+doc_txt := $(doc_name).txt
+
+## ----------------------------------------------------------------------
+## General definitions
+RMR := /bin/rm -fr
+
+## ----------------------------------------------------------------------
+## Targets
+all: $(doc_sgml)
+
+ nsgmls -wall -E20 -gues $^
+ debiandoc2html $^
+ debiandoc2latexpdf -p letter $^
+ debiandoc2text $^
+
+clean:
+
+ $(RMR) $(doc_html) $(doc_pdf) $(doc_txt)
+
+## ----------------------------------------------------------------------
Added: packages/sgml-base-doc/trunk/POLICY
URL: http://svn.debian.org/wsvn/debian-xml-sgml/packages/sgml-base-doc/trunk/POLICY?rev=1147&op=file
==============================================================================
--- packages/sgml-base-doc/trunk/POLICY (added)
+++ packages/sgml-base-doc/trunk/POLICY Tue Sep 2 12:01:03 2008
@@ -1,0 +1,121 @@
+Debian SGML/XML Policy (draft)
+==============================
+
+Currently, the policy is spread over several documents:
+
+ - RECOMMENDATIONS.lsb
+ - EXPLANATIONS.lsb
+ - RECOMMENDATIONS.fsh
+ - "SGML Entity Management"
+ - this file
+
+In the near future this will all be integrated into a single official
+document, with the exception of RECOMMENDATIONS.fsh which will be a
+part of FHS v2.2.
+
+Besides the directory structure described in RECOMMENDATIONS.lsb, we
+will also support a non-versioned directory structure as proposed by
+Mark Johnson (excerpt from his message on debian-sgml):
+
+--
+
+Directory Structure Comment:
+---------------------
+On the proposed directory structure -- grouped by classes of dtds rather
+ than file function:
+
+-Current dir structure:
+
+/usr/[share or lib]/sgml/
+ dtd/
+ stylesheet/
+ entities/
+
+-Proposed:
+
+/usr/share/sgml/docbook/
+ sgml-dtd-3.1/
+ sgml-dtd-4.0/
+ xml-dtd-4.0/ (the DocBook DTD)
+ dsssl-stylesheets-1.54/
+ xsl-stylesheets-1.12/
+
+Wouldn't a hybrid of the two make much more sense? Something like:
+
+/usr/share/sgml/docbook/
+ dtd/
+ stylesheet/
+ entities/
+
+The proposed structure looks unnecessarily messy, and harder to maintain.
+
+--
+
+
+Package dependencies
+--------------------
+
+All SGML and XML packages that provide a DTD or entity description file
+have to depend on the "sgml-base" package. This package implements the
+necessary infrastructure as described in the files RECOMMENDATIONS.lsb
+and RECOMMENDATIONS.fsh.
+
+Please don't modify the super catalog and the centralized catalogs
+directly in the postinst/prerm scripts of your package. Please use
+update-catalog(8) for that purpose.
+
+
+Example
+-------
+
+Here is a simple example: Consider the package "foo" which provides
+the SGML DTD foo.dtd and an entity description file "foo-general".
+The package installs the following files:
+
+ /usr/share/sgml/foo/sgml-dtd-<version>/dtd/foo.dtd
+ /usr/share/sgml/foo/sgml-dtd-<version>/entities/foo-general
+ /usr/share/sgml/foo/sgml-dtd-<version>/catalog
+
+The catalog file can look like this:
+
+ DOCTYPE foodoc foo/sgml-dtd-<version>/dtd/foo.dtd
+ ENTITY %foo-general foo/sgml-dtd-<version>/entities/foo-general
+
+That's the postinst script:
+
+ #!/bin/sh
+ set -e
+ if [ "$1" = configure ]
+ then
+ CENCAT=/etc/sgml/foo-<version>.cat
+ ORDCAT=/usr/share/sgml/foo-<version>/catalog
+ update-catalog --add $CENCAT $ORDCAT
+ update-catalog --add --super $CENCAT
+ fi
+ #DEBHELPER
+ exit 0
+
+and the prerm script:
+
+ #!/bin/sh
+ set -e
+ if [ "$1" = remove ]
+ then
+ CENCAT=/etc/sgml/foo-<version>.cat
+ ORDCAT=/usr/share/sgml/foo-<version>/catalog
+ update-catalog --remove --super $CENCAT
+ update-catalog --remove $CENCAT $ORDCAT
+ fi
+ #DEBHELPER
+ exit 0
+
+Please check the update-catalog(8) manpage for details.
+
+
+Feedback
+--------
+
+Please send me an email for bugs/suggestions/critics on this policy.
+
+February 2001
+Ardo van Rangelrooij <ardo at debian.org>
Added: packages/sgml-base-doc/trunk/README
URL: http://svn.debian.org/wsvn/debian-xml-sgml/packages/sgml-base-doc/trunk/README?rev=1147&op=file
==============================================================================
--- packages/sgml-base-doc/trunk/README (added)
+++ packages/sgml-base-doc/trunk/README Tue Sep 2 12:01:03 2008
@@ -1,0 +1,18 @@
+IMPORTANT NOTE
+--------------
+
+This version of sgml-base starts the transition of /usr/lib/sgml to
+/usr/share/sgml. The documentation is not yet integrated into one
+single nice document with good examples and guidelines. This will
+definitely change in the near future. Also the support in the form
+of tools is still in its infancy. This version mainly only moves
+the catalogs into place and introduces a tool called update-catalog.
+
+
+Feedback
+--------
+
+Please send me an email for bugs/suggestions/critics on this note.
+
+February 2001
+Ardo van Rangelrooij <ardo at debian.org>
Added: packages/sgml-base-doc/trunk/RECOMMENDATIONS.fhs
URL: http://svn.debian.org/wsvn/debian-xml-sgml/packages/sgml-base-doc/trunk/RECOMMENDATIONS.fhs?rev=1147&op=file
==============================================================================
--- packages/sgml-base-doc/trunk/RECOMMENDATIONS.fhs (added)
+++ packages/sgml-base-doc/trunk/RECOMMENDATIONS.fhs Tue Sep 2 12:01:03 2008
@@ -1,0 +1,71 @@
+File system recommendations for SGML and XML layout
+---------------------------------------------------
+
+Introduction
+------------
+
+In a normalisation effort, about thirty people, including packagers
+of some Linux distributions, and developers of SGML related tools such
+as the SGML-Tools and DocBook Tools project, discussed informally and
+agreed on a series of recommendations that will be submitted as a draft
+to the Linux Standard Base project. A reference implementation will also
+be done as part of the DocBook-tools project.
+
+This document addresses the FHS part of the project.
+
+This document makes several references to "catalogs": these files
+represent the dorsal spine of a SGML or XML system. They are mainly used
+to map things (that are called "entities" in SGML or XML terminology)
+into real file names. A catalog can reference other catalogs through
+pointer directives (CATALOG, DELEGATE). For more information, see the
+Open Catalogs standard at <A HREF="http://www.oasis-open.org">http://www.oasis-open.org</A>.
+
+/etc/sgml/
+----------
+
+In /etc/sgml one can find configuration files that describe the installed
+components of a SGML or XML system.
+
+Files found there include:
+
+ *.conf: generic configuration files
+ *.cat: DTD-specific centralized catalogs
+ catalog: the super catalog
+
+The generic configuration files define high-level parameters of the SGML
+or XML system.
+
+The "centralized catalogs" are catalogs that reference through pointers
+all the other catalogs that are needed to use a given DTD. The referenced
+files include the DTD's catalog, style sheets catalogs, character entities
+sets catalogs, etc. All the files that are referenced reside somewhere
+under /usr/share/sgml.
+
+The "super catalog" references through pointers all the centralized
+catalogs. Unlike the centralized catalogs, it does not guarantee the
+absence of definition conflicts between referenced catalogs.
+
+At least for the present, all XML documents are also SGML documents,
+so it seems unnecessary to create /etc/xml.
+
+/usr/share/sgml/
+----------------
+
+In /usr/share/sgml reside architecture-independent files used by SGML
+or XML applications: ordinary catalogs (not the centralized ones), DTDs,
+entities, style sheets, and other declarative files, if any.
+
+It is organized at top-level into DTD-specific subdirectories, when
+applicable:
+ docbook/
+ tei/
+ html/
+ mathml/
+ ...
+
+Other files that are not specific to a given DTD may reside in their own
+directory. When we say "specific to a DTD", it does not mean that those
+files describe a DTD, but only that they are to be used with this DTD.
+
+At least for the present, all XML documents are also SGML documents,
+so it seems unnecessary to create /usr/share/xml.
Added: packages/sgml-base-doc/trunk/RECOMMENDATIONS.lsb
URL: http://svn.debian.org/wsvn/debian-xml-sgml/packages/sgml-base-doc/trunk/RECOMMENDATIONS.lsb?rev=1147&op=file
==============================================================================
--- packages/sgml-base-doc/trunk/RECOMMENDATIONS.lsb (added)
+++ packages/sgml-base-doc/trunk/RECOMMENDATIONS.lsb Tue Sep 2 12:01:03 2008
@@ -1,0 +1,315 @@
+Recommendations for DocBook, SGML and XML processing
+----------------------------------------------------
+
+Introduction
+------------
+
+In a normalisation effort, about thirty people, including packagers
+of some Linux distributions, and developers of SGML related tools such
+as the SGML-Tools and DocBook Tools project, discussed informally and
+agreed on a series of recommendations that will be submitted as a draft
+to the Linux Standard Base project. A reference implementation will also
+be done as part of the DocBook-tools project.
+
+This document's redaction started as an attempt to end the nightmare
+of DocBook distributions, but it appeared quickly to be generic enough
+to apply to any SGML or XML DTD. Explanations about the reasons
+for all our choices are given in a separate document.
+
+Following a list of definitions, you will find a set of recommendations:
+R001 - SGML Directory layout
+R002 - DocBook Directory layout
+ (standard names for directories, their contents)
+R003 - Open Catalogs usage for SGML
+R004 - Open Catalogs usage for DocBook
+ (for the centralized catalogs and for the individual catalogs)
+R005 - Configuration files
+ (other /etc/sgml files)
+R006 - ISO-entities
+ (file names and FPI declarations)
+R007 - Packages
+ (how to package this type of material)
+
+We'd like to thank the following people who have participated intensively
+in this normalisation effort:
+ Camille Begnis (MandrakeSoft) <camille at mandrakesoft.com>
+ Eric Bischoff (Caldera, KDE) <eric at caldera.de>
+ Karl Eichwalder (SuSE) <ke at suse.de>
+ Mark Galassi (DocBook-tools) <rosalia at lanl.gov>
+ Jorge Godoy (Conectiva) <godoy at conectiva.com.br>
+ Cees de Groot (SGML-tools) <cg at cdegroot.com>
+ Jochem Huhmann <joh at revier.com>
+ David Mason (RedHat, Gnome) <dcm at redhat.com>
+ Manoj Srivastava (Debian) <srivasta at datasync.com>
+ Norman Walsh (Sun, OASIS) <ndw at nwalsh.com>
+and all the other many people that helped with their own contribution.
+
+
+Definitions
+-----------
+
+In the scope of this document, we will use the following terms:
+
+SGML application:
+ Any program used to view, edit, convert, process or apply any
+ kind of treatment to a document written using a SGML or XML DTD
+ (Document Type Definition). This includes command-line utilities
+ as well as GUI-based applications.
+
+SGML converter:
+ A SGML application, or a part of a bigger SGML application,
+ used to convert from a given SGML-based input format to a given
+ output format.
+
+frontend:
+ A part of a SGML converter used to analyse the input format
+
+backend:
+ A part of a SGML converter used to analyse the output format
+
+helper:
+ A stand-alone application used by a SGML converter to accomplish
+ the conversion itself.
+
+Style sheets:
+ Declarations or scripts that define formatting during the
+ conversion process. They can be written in any style sheets
+ language: DSSSL, FOSIs, XSL, ...
+
+Open Catalog:
+ A set of directives defined by OASIS, mostly used for defining
+ equivalences between FPIs (Formal Public Identifiers) and real
+ file names (see TR9401:1997 on <A HREF="http://www.oasis-open.org">http://www.oasis-open.org</A>).
+
+Centralized catalog:
+ An Open Catalog that includes only comments and CATALOG
+ directives pointing to other catalogs (or DELEGATE directives
+ if supported).
+
+Super catalog:
+ An Open Catalog pointing to all the centralized catalogs.
+
+Package:
+ A set of files assembled together for distribution. It includes
+ RPMs, DEBs and any other kind of packaging system.
+
+
+R001 - SGML Directory layout
+----------------------------
+
+/etc/sgml/
+ Configuration files, including centralized catalogs.
+
+ It includes:
+ *.conf: generic configuration files
+ sgml-docbook.cat, tei.cat, ...: DTD-specific centralized catalogs
+ catalog: the super catalog
+ ...
+
+/usr/share/sgml/
+ Architecture-independent files used by SGML applications: Open
+ Catalogs (not the centralized ones), DTDs, entities, style sheets,
+ and other declarative files, if any.
+
+ It is organized into DTD-specific subdirectories:
+ docbook/
+ tei/
+ html/
+ ...
+
+At least for the present, all XML documents are also SGML
+documents, so it seems unnecessary to create /usr/share/xml and /etc/xml.
+
+
+R002 - DocBook Directory layout
+-------------------------------
+
+This is the layout for a Jade-based or an Openjade-based system. DocBook
+applications based on other parsers, or even any other SGML application,
+can be based on this layout as well.
+
+In /usr/share/sgml, the upper level directories identify the DTD that
+is concerned. Things that are not DTD-specific go directly into
+/usr/share/sgml under their own directory.
+
+The lower level directories are package-related. They are
+also version-numbered.
+
+/usr/share/sgml/
+ sgml-iso-entities-8879.1986/
+ xml-iso-entities-8879.1986/
+ (the ISO entities)
+ jade-1.2.1/
+ openjade-1.3/
+ ...
+ (the parsers and DSSSL engines
+ architecture-independent files)
+ ...
+
+/usr/share/sgml/docbook/
+ sgml-dtd-3.1/
+ sgml-dtd-4.0/
+ xml-dtd-4.0/
+ (the DocBook DTD)
+ dsssl-stylesheets-1.54/
+ xsl-stylesheets-1.12/
+ (DSSSL style sheets for DocBook)
+ kde-customization-0.1/
+ gnome-customization-0.1/
+ ldp-customization-0.1/
+ (customized DTDs, entities and style sheets for
+ the various projects)
+ ...
+
+(version number examples are arbitrary in this list)
+
+
+R003 - Open Catalog usage for SGML
+----------------------------------
+
+Open Catalog files include:
+- the individual catalogs provided with the DTDs, sylesheets or entities.
+- the centralized catalogs used as central source of information
+ that is specific to docbook, tei, or any other DTD
+- the super catalog that references indirectly all the available
+ catalog files
+
+The centralized catalog file names must end in .cat and reside in
+/etc/sgml. They contain only comments and CATALOG directives pointing
+to the "real" catalogs, like:
+
+ -- sample contents of /etc/sgml/foo-1.05.cat --
+ CATALOG /usr/share/sgml/foo/xml-dtd-1.05/catalog
+ CATALOG /usr/share/sgml/foo/xsl-stylesheets-0.1/catalog
+
+One can use DELEGATE instead of CATALOG if this directive is known to
+be supported.
+
+The centralized catalogs are DTD-specific and can be version-numbered.
+
+Here are examples of such centralized catalogs:
+/etc/sgml/
+ sgml-docbook.cat
+ sgml-docbook-3.1.cat
+ sgml-docbook-4.0.cat
+ xml-docbook-4.0.cat
+
+Version-less centralized catalogs could be only symbolic links to the
+latest version (or to any other older version).
+
+/etc/sgml/catalog is the "super catalog". It contains CATALOG pointers
+to all the centralized catalogs:
+
+ -- sample contents of /etc/sgml/catalog --
+ CATALOG /etc/sgml/sgml-docbook.cat
+ CATALOG /etc/sgml/xhtml.cat
+ CATALOG /etc/sgml/mathml.cat
+
+One can use DELEGATE instead of CATALOG if this directive is known to
+be supported.
+
+It should not point to centralized catalogs that are merely symbolic links
+and therefore are already mentioned.
+
+The users should be able to define their own centralized catalogs and
+their own super catalog in their home directories:
+ $HOME/.sgml-docbook.cat
+ $HOME/.catalog
+
+The SGML applications are not supposed to use centralized catalogs,
+although their use is stronlgy encouraged: if other mechanisms allow
+one to locate the real catalogs, they can be used as well. However
+distribution packagers should always take care of feeding the right
+entries into the super catalog and the centralized catalogs. The interface
+for a script named "install-catalog" that does these maintenance tasks
+is described here:
+
+ install-catalog --add|--remove <centralized_catalog> <ordinary_catalog>
+
+Example:
+
+ install-catalog --add \
+ /etc/sgml/sgml-docbook-3.1 \
+ /usr/share/sgml/docbook/dsssl-stylesheets-1.54/catalog
+
+The other catalogs should be placed in subdirectories of /usr/share/sgml.
+They should all be named "catalog". They are the ones who do the real
+work of mapping the FPIs to file names (among other tasks).
+
+
+R004 - Open Catalog usage for DocBook
+-------------------------------------
+
+This recomendation is merely a consequence of the preceeding
+recomendations.
+
+For a Jade- or Openjade-based distribution of DocBook, we suggest the
+following names. Again, other SGML or XML DTDs can be based on this
+structure.
+
+/etc/sgml/
+ sgml-docbook.cat
+ xml-docbook.cat
+ sgml-docbook-3.0.cat
+ sgml-docbook-3.1.cat
+ sgml-docbook-4.0.cat
+ xml-docbook-4.0.cat
+
+/usr/share/sgml/sgml-iso-entities-8879.1986/catalog
+/usr/share/sgml/xml-iso-entities-8879.1986/catalog
+
+/usr/share/sgml/jade-1.2.1/catalog
+
+/usr/share/sgml/openjade-1.0/catalog
+
+/usr/share/sgml/docbook/sgml-dtd-3.0/catalog
+/usr/share/sgml/docbook/sgml-dtd-3.1/catalog
+/usr/share/sgml/docbook/sgml-dtd-4.0/catalog
+/usr/share/sgml/docbook/xsl-dtd-4.0/catalog
+
+/usr/share/sgml/docbook/dsssl-stylesheets-1.54/catalog
+/usr/share/sgml/docbook/xsl-stylesheets-1.12/catalog
+
+
+R005 - Configuration files
+--------------------------
+
+Other configuration files may also reside in /etc/sgml, either
+DTD-specific or application-specific. Their name should end in ".conf" and
+they should follow ordinary rules for files residing in /etc as defined by
+LSB. The user should be able to redefine them in his/her home directory.
+
+Their syntax and purpose is not defined in this document.
+
+
+R006 - Iso-entities
+-------------------
+
+The file names should be fixed to:
+ ISOamsa.ent ISOamsb.ent ...
+
+The identifiers should be fixed to:
+ "ISO 8879:1986//ENTITIES Added Math Symbols: Arrow Relations//EN"
+
+In the transitory period, symbolic links and duplicate declarations will
+be allowed as a means to preserve the compatibility with previous naming
+schemes.
+
+
+R007 - Packages
+---------------
+
+C programs can get compiled with any version of a given compiler. SGML
+documents can't use any version of a given DTD. They need the
+corresponding DTD to reside on the same system, or at least to be
+reachable. The various versions of a given DTD in turn may imply certain
+versions of the style sheets.
+
+This leads to a unusual situation where the old DTDs and style sheets
+should not be replaced during a package update.
+
+We would like to make the solutions to achieve this aware to distribution
+packagers. They may choose to:
+ - put the version number in the package name field
+ (example: docbook-dtd-3.1-1.0.rpm)
+ - not put the version number and use subpackages for each version
Added: packages/sgml-base-doc/trunk/debian/TODO
URL: http://svn.debian.org/wsvn/debian-xml-sgml/packages/sgml-base-doc/trunk/debian/TODO?rev=1147&op=file
==============================================================================
--- packages/sgml-base-doc/trunk/debian/TODO (added)
+++ packages/sgml-base-doc/trunk/debian/TODO Tue Sep 2 12:01:03 2008
@@ -1,0 +1,23 @@
+------------------------------------------------------------------------------
+To do list for sgml-base-doc
+------------------------------------------------------------------------------
+
+BUGS:
+------------------------------------------------------------------------------
+Number Description
+------------------------------------------------------------------------------
+------------------------------------------------------------------------------
+
+WISHLIST:
+------------------------------------------------------------------------------
+Number Description
+------------------------------------------------------------------------------
+------------------------------------------------------------------------------
+
+VARIOUS:
+------------------------------------------------------------------------------
+Description
+------------------------------------------------------------------------------
+* rewrite to reflect current
+* clean out what's not needed anymore
+------------------------------------------------------------------------------
Added: packages/sgml-base-doc/trunk/debian/changelog
URL: http://svn.debian.org/wsvn/debian-xml-sgml/packages/sgml-base-doc/trunk/debian/changelog?rev=1147&op=file
==============================================================================
--- packages/sgml-base-doc/trunk/debian/changelog (added)
+++ packages/sgml-base-doc/trunk/debian/changelog Tue Sep 2 12:01:03 2008
@@ -1,0 +1,35 @@
+sgml-base-doc (1.16) unstable; urgency=low
+
+ * debian/control: upgraded to Debian Policy 3.6.1 (no changes)
+ * debian/control: changed 'Maintainer' to 'Debian XML/SGML Group
+ <debian-xml-sgml-pkgs at lists.alioth.debian.org>' and added current
+ maintainer to 'Uploaders'
+
+ -- Ardo van Rangelrooij <ardo at debian.org> Thu, 22 Apr 2004 07:54:27 -0500
+
+sgml-base-doc (1.15) unstable; urgency=low
+
+ * Removed document sources from binary package and indicated in
+ README.Debian how to get the source package
+ * debian/rules: moved debhelper compatibility level setting to
+ 'debian/compat' per latest debhelper best practices
+ * debian/control: changed build dependency on 'debhelper' to '(>= 4.1)'
+ * debian/control: upgraded to Debian Policy 3.6.0 (no changes)
+
+ -- Ardo van Rangelrooij <ardo at debian.org> Tue, 12 Aug 2003 21:02:30 -0500
+
+sgml-base-doc (1.14) unstable; urgency=low
+
+ * debian/rules: upgraded to debhelper v4
+ * debian/control: changed build dependency on debhelper accordingly
+ * debian/rules: migrated from 'dh_movefiles' to 'dh_install'
+ * debian/rules: split off 'install' target from 'binary-indep' target
+ * debian/copyright: added pointer to license
+
+ -- Ardo van Rangelrooij <ardo at debian.org> Sat, 10 Aug 2002 13:58:20 -0500
+
+sgml-base-doc (1.13) unstable; urgency=low
+
+ * Initial release as a separate package
+
+ -- Ardo van Rangelrooij <ardo at debian.org> Sun, 17 Feb 2002 13:34:28 -0600
Added: packages/sgml-base-doc/trunk/debian/compat
URL: http://svn.debian.org/wsvn/debian-xml-sgml/packages/sgml-base-doc/trunk/debian/compat?rev=1147&op=file
==============================================================================
--- packages/sgml-base-doc/trunk/debian/compat (added)
+++ packages/sgml-base-doc/trunk/debian/compat Tue Sep 2 12:01:03 2008
@@ -1,0 +1,1 @@
+4
Added: packages/sgml-base-doc/trunk/debian/control
URL: http://svn.debian.org/wsvn/debian-xml-sgml/packages/sgml-base-doc/trunk/debian/control?rev=1147&op=file
==============================================================================
--- packages/sgml-base-doc/trunk/debian/control (added)
+++ packages/sgml-base-doc/trunk/debian/control Tue Sep 2 12:01:03 2008
@@ -1,0 +1,18 @@
+Source: sgml-base-doc
+Section: doc
+Priority: optional
+Maintainer: Debian XML/SGML Group <debian-xml-sgml-pkgs at lists.alioth.debian.org>
+Uploaders: Ardo van Rangelrooij <ardo at debian.org>
+Standards-Version: 3.6.1
+Build-Depends-Indep: debhelper (>= 4.1), debiandoc-sgml, libpaperg, sp, tetex-bin, tetex-extra
+
+Package: sgml-base-doc
+Section: doc
+Priority: optional
+Architecture: all
+Conflicts: sgml-base (<= 1.12)
+Replaces: sgml-base (<= 1.12)
+Suggests: sgml-base (>= 1.13)
+Description: Documentation for sgml-base
+ This package contains the documentation for sgml-base in HTML, PDF
+ and plain text format.
Added: packages/sgml-base-doc/trunk/debian/copyright
URL: http://svn.debian.org/wsvn/debian-xml-sgml/packages/sgml-base-doc/trunk/debian/copyright?rev=1147&op=file
==============================================================================
--- packages/sgml-base-doc/trunk/debian/copyright (added)
+++ packages/sgml-base-doc/trunk/debian/copyright Tue Sep 2 12:01:03 2008
@@ -1,0 +1,20 @@
+This is the Debian package of the documentation for sgml-base.
+
+It was assembled by Ardo van Rangelrooij <ardo at debian.org>. It is
+currently maintained by Ardo van Rangelrooij <ardo at debian.org>.
+
+----------------------------------------------------------------------
+
+Copyright of the sgml-base manual:
+
+Copyright (c) 1998 Manoj Srivastava
+
+This manual is free software; you may redistribute it and/or modify it
+under the terms of the GNU General Public License as published by the
+Free Software Foundation; either version 2, or (at your option) any
+later version.
+
+----------------------------------------------------------------------
+
+On a Debian system a copy of the GNU General Public License can be
+found in the file '/usr/share/common-licenses/GPL'.
Added: packages/sgml-base-doc/trunk/debian/rules
URL: http://svn.debian.org/wsvn/debian-xml-sgml/packages/sgml-base-doc/trunk/debian/rules?rev=1147&op=file
==============================================================================
--- packages/sgml-base-doc/trunk/debian/rules (added)
+++ packages/sgml-base-doc/trunk/debian/rules Tue Sep 2 12:01:03 2008
@@ -1,0 +1,55 @@
+#!/usr/bin/make -f
+## ----------------------------------------------------------------------
+## debian/rules : package script for sgml-base-doc
+## ----------------------------------------------------------------------
+
+## ----------------------------------------------------------------------
+## uncomment this to turn on verbose mode
+#export DH_VERBOSE=1
+
+## ----------------------------------------------------------------------
+TMP_DIR = debian/tmp
+
+## ----------------------------------------------------------------------
+## targets
+
+clean:
+ dh_testdir
+ dh_testroot
+ [ ! -f Makefile ] || $(MAKE) clean
+ dh_clean
+ rm -f build-stamp install-stamp
+
+build: build-stamp
+build-stamp:
+ dh_testdir
+ $(MAKE)
+ touch build-stamp
+
+install: install-stamp
+install-stamp: build
+ dh_testdir
+ dh_testroot
+ dh_clean -k
+ dh_installdirs
+ touch install-stamp
+
+binary-indep: build install
+ dh_testdir
+ dh_testroot
+ dh_installdocs
+ dh_installchangelogs
+ dh_compress
+ dh_fixperms
+ dh_installdeb
+ dh_gencontrol
+ dh_md5sums
+ dh_builddeb
+
+binary-arch:
+
+binary: binary-indep binary-arch
+
+.PHONY: clean build install binary-indep binary-arch binary
+
+## ----------------------------------------------------------------------
Propchange: packages/sgml-base-doc/trunk/debian/rules
------------------------------------------------------------------------------
svn:executable =
Added: packages/sgml-base-doc/trunk/debian/sgml-base-doc.README.Debian
URL: http://svn.debian.org/wsvn/debian-xml-sgml/packages/sgml-base-doc/trunk/debian/sgml-base-doc.README.Debian?rev=1147&op=file
==============================================================================
--- packages/sgml-base-doc/trunk/debian/sgml-base-doc.README.Debian (added)
+++ packages/sgml-base-doc/trunk/debian/sgml-base-doc.README.Debian Tue Sep 2 12:01:03 2008
@@ -1,0 +1,18 @@
+sgml-base-doc for Debian
+========================
+
+The source files for the documentation in this package can be obtained
+as follows:
+
+1. Include a "deb-src" line in the "/etc/sources.list", e.g.
+
+ deb-src http://ftp.us.debian.org/debian/ unstable main
+
+ For more information on this see the manual page sources.list(5).
+
+2. Download the source withthe following command:
+
+ apt-get source sgml-base-doc
+
+--
+Ardo van Rangelrooij <ardo at debian.org>
Added: packages/sgml-base-doc/trunk/debian/sgml-base-doc.doc-base
URL: http://svn.debian.org/wsvn/debian-xml-sgml/packages/sgml-base-doc/trunk/debian/sgml-base-doc.doc-base?rev=1147&op=file
==============================================================================
--- packages/sgml-base-doc/trunk/debian/sgml-base-doc.doc-base (added)
+++ packages/sgml-base-doc/trunk/debian/sgml-base-doc.doc-base Tue Sep 2 12:01:03 2008
@@ -1,0 +1,18 @@
+Document: sgml_layout
+Title: SGML Entity Management
+Author: Manoj Srivastava <srivasta at debian.org>
+Abstract: This document provides guidelines for implementation dependent Entity management of SGML entities for Debian systems.
+Section: Debian
+
+Format: debiandoc-sgml
+Files: /usr/share/doc/sgml-base-doc/sgml_layout.sgml.gz
+
+Format: HTML
+Index: /usr/share/doc/sgml-base-doc/sgml_layout.html/index.html
+Files: /usr/share/doc/sgml-base-doc/sgml_layout.html/*.html
+
+Format: PDF
+Files: /usr/share/doc/sgml-base-doc/sgml_layout.pdf.gz
+
+Format: text
+Files: /usr/share/doc/sgml-base-doc/sgml_layout.txt.gz
Added: packages/sgml-base-doc/trunk/debian/sgml-base-doc.docs
URL: http://svn.debian.org/wsvn/debian-xml-sgml/packages/sgml-base-doc/trunk/debian/sgml-base-doc.docs?rev=1147&op=file
==============================================================================
--- packages/sgml-base-doc/trunk/debian/sgml-base-doc.docs (added)
+++ packages/sgml-base-doc/trunk/debian/sgml-base-doc.docs Tue Sep 2 12:01:03 2008
@@ -1,0 +1,8 @@
+POLICY
+README
+sgml_layout.html
+sgml_layout.pdf
+sgml_layout.txt
+EXPLANATIONS.lsb
+RECOMMENDATIONS.lsb
+RECOMMENDATIONS.fhs
Added: packages/sgml-base-doc/trunk/sgml_layout.sgml
URL: http://svn.debian.org/wsvn/debian-xml-sgml/packages/sgml-base-doc/trunk/sgml_layout.sgml?rev=1147&op=file
==============================================================================
--- packages/sgml-base-doc/trunk/sgml_layout.sgml (added)
+++ packages/sgml-base-doc/trunk/sgml_layout.sgml Tue Sep 2 12:01:03 2008
@@ -1,0 +1,171 @@
+<!doctype debiandoc system>
+
+<debiandoc>
+
+ <book>
+
+ <titlepag>
+ <title>SGML Entity Management</title>
+ <author>
+ <name>Manoj Srivastava</name>
+ <email>srivasta at debian.org</email>
+ </author>
+ <version><date></version>
+ <abstract>
+ This document provides a guidelines for implementation
+ dependent Entity management of SGML entities for Debian
+ systems. This defines the mapping of <em>External Public
+ Identifiers</em> to <em>System Identifiers</em>. (In other
+ words, this document covers the use of <tt>/usr/lib/sgml</tt>,
+ entity naming, and catalog files.
+ </abstract>
+
+ <copyright>
+ <copyrightsummary>Copyright ©1998 Manoj
+ Srivastava
+ </copyrightsummary>
+ <p>
+ This manual is free software; you may redistribute it and/or
+ modify it under the terms of the GNU General Public License
+ as published by the Free Software Foundation; either version
+ 2, or (at your option) any later version.
+ </p>
+ </copyright>
+ </titlepag>
+
+ <toc detail="sect">
+
+ <chapt id="intro">
+ <heading>Introduction and Scope</heading>
+ <p>
+ This document was written by Manoj Srivastava
+ <email>srivasta at debian.org</email> with contributions from Mark
+ W. Eichin <email>eichin at kitten.gen.ma.us</email> and Adam P. Harris
+ <email>aph at debian.org</email>. This document is part of the
+ <prgn>sgml-base</prgn> package.
+ </p>
+
+ <p>
+ This guideline is intended to be intepreted as SGML sub-policy (not
+ official policy). While this document does not carry the weight of
+ official policy, it is sufficient basis for the submission of bugs
+ against a package. This may change at a latter date.
+ </p>
+
+ <p>
+ Entity Management is generally left up to the implementation,
+ and hence there are no extant Standards that cover
+ this. However, lack of an established convention would prevent
+ different segments of the SGML subsystem from co-operating
+ with each other, hence it is important that a policy be
+ established so that SGML package maintainers may depend on
+ other parts of the system behaving consistently.
+ </p>
+ </chapt>
+
+ <chapt id="mapping">
+ <heading>Proposed mapping of public identifiers to system
+ identifiers</heading>
+ <p>
+ SGML can refer to an external file (really an entity) with an
+ <var>external identifier</var>: this is a <var>public identifier</var>
+ or a <var>system identifier</var>, or both.</p>
+
+ <p>
+ A typical public identifier looks like
+ <example>
+ PUBLIC "ISO 8879-1986//ENTITIES Added Latin 1//EN"
+ </example>
+ where <tt>ISO 8879-1986</tt> is the owner, <tt>ENTITIES</tt> is the
+ text class and <tt>Added Latin 1</tt> is the text description, and
+ <tt>EN</tt> is language.
+ </p>
+
+ <p>
+ A system identifier looks like
+ <example>
+ SYSTEM "htmlplus.dtd"
+ </example>
+ where <tt>htmlplus.dtd</tt> is a system-specific identifier.
+ </p>
+
+ <p>
+ To map external identifiers to file names, one should first try the
+ system identifier, as a file name, and then search entity catalog
+ files and then search the list of file names derived from the public
+ identifier. The catalog format is according to SGML/Opens resolution
+ on entity management. The catalog consists of a series of entries and
+ comments. A comment is delimited by <tt>--</tt> like in a markup
+ declaration.
+ </p>
+
+ <p>
+ The fallback derivation of the file name is modelled after the
+ <prgn>sgmls</prgn> environment variable <var>SGML_PATH</var>,
+ and Emacs <prgn>psgml</prgn> mode's <var>sgml-public-map</var>
+ variable. There does not seem to be any official standards
+ (this is left to the implementation), so this standard is
+ simply an abstraction of real-world practice of SGML
+ tools, and shall now be the standard for Debian systems, since
+ this is the convention currently followed by all applications
+ currently in Debian.</p>
+
+ <p>
+ Contiguous white space is compacted to a single space and
+ replaced with an underscore (<tt>_</tt>); the characters
+ <tt>/</tt> to <tt>%</tt> are also replaced with <tt>_</tt>.
+ The text class is down-cased. The language specifier (i.e.,
+ <tt>//EN</tt>) and anything following it should be
+ removed.
+ </p>
+ </chapt>
+
+ <chapt id="Other">
+ <heading>Location of miscellaneous files</heading>
+ <p>
+ There are a number of other files, though not entities
+ referenced by Document instances, are still required by the
+ SGML subsytem to parse or validate the document. These files
+ are also covered by this document.
+ <enumlist>
+ <item>
+ <p>Declaration Files: Any declaration file should be put
+ in <tt>/usr/lib/sgml/declaration</tt></p>
+ </item>
+ <item>
+ <p>
+ Notations: These files go in
+ <tt>/usr/lib/sgml/notation</tt>.
+ </p>
+ </item>
+ </enumlist>
+ </p>
+ </chapt>
+
+ <chapt id="examples"><heading>Examples</heading>
+ <p>
+ A few public and system identifiers pairings are shown below.
+ <example>
+PUBLIC "ISO 8879-1986//ENTITIES Added Latin 1//EN"
+/usr/lib/sgml/ISO_8879-1986/entities/Added_Latin_1
+
+"ISO 8879-1986//ENTITIES Added Math Symbols: Arrow Relations//EN"
+/usr/lib/sgml/ISO_8879-1986/entities/Added_Math_Symbols:_Arrow_Relations
+
+"-//IETF//DTD HTML Level 3//EN//3.0"
+/usr/lib/sgml/IETF/dtd/HTML_Level_3.0
+
+"-//IETF//DTD HTML Strict Level 3//EN"
+/usr/lib/sgml/IETF/dtd/HTML_Strict_Level_3
+
+"-//USA-DOD//DTD Table Model 951010//EN"
+/usr/lib/sgml/USA-DOD/dtd/Table_Model_951010
+ </example>
+ </p>
+
+ <p>The first four actually exist in Debian.</p>
+ </chapt>
+
+ </book>
+
+</debiandoc>
More information about the debian-xml-sgml-commit
mailing list