Date: Sat, 29 Jan 2000 15:42:15 +0100 (CET) From: Karlheinz.Eckmeier@t-online.de To: FreeBSD-gnats-submit@freebsd.org Subject: docs/16439: fdp-primer - difficulties with split SGML files Message-ID: <200001291442.PAA00654@abakus.my.domain>
next in thread | raw e-mail | index | archive | help
>Number: 16439
>Category: docs
>Synopsis: fdp-primer - difficulties with split SGML files
>Confidential: no
>Severity: non-critical
>Priority: medium
>Responsible: freebsd-doc
>State: open
>Quarter:
>Keywords:
>Date-Required:
>Class: change-request
>Submitter-Id: current-users
>Arrival-Date: Sat Jan 29 06:50:02 PST 2000
>Closed-Date:
>Last-Modified:
>Originator: Karlheinz Eckmeier
>Release: FreeBSD 3.3-RELEASE i386
>Organization:
>Environment:
doc-all from cvsup.de.FreeBSD.org ( release=cvs tag=. )
xemacs-20.4 + psgml 1.2.0
>Description:
The last part in of "6.3.1.1.3 directory/chapter/sgml" says:
<quote>
Each chapter.sgml file will not be a complete SGML document. In
particular, they will not have their own DOCTYPE line at the start
of the file.
This is unfortunate for two reasons;
* It makes it impossible to treat these as generic SGML files and
simply convert them to HTML, RTF, PS, and other formats in the
same way the main Handbook is generated. This would force you to
rebuild the Handbook every time you want to see the effect a change
as had on just one chapter.
* Emacs' sgml-mode can not use it to determine the DTD to use, losing
useful benefits of sgml-mode (element completion, automatic
validation, and so on).
</quote>
>How-To-Repeat:
>Fix:
I propose to change or to drop these two paragraphs because of
the following reasons:
1) Regarding the first paragraph I would like to suggest a different
approach. It is true, one cannot treat these "partial" SGML-files
the same as a complete SGML document. But using a little workaround
would allow to generate the output formats of only the part
actually being worked on:
- Create a template SGML file containing all the elements the
partial SGML files is missing (DOCTYPE, <book>,<part>). It also
contains an template external general entity to include a
partial SGML file at the appropriate place.
- Create a script with the following functions:
+ When called with a partial SGML file as parameter it
passes the template file through sed to change the template
entity to include the specified partial SGML file and thus
creating a valid SGML document.
+ Start the appropriate make process to generate the desired
output format.
+ Print the contents of the jade log file to stdout
- Configure the compile command of xemacs to start the above
script when editing a SGML file. All the errors discovered by
jade (i.e. the contents of the jade log file) will show up in
the compilation buffer of xemacs and can be stepped through via
the "next-error" command of xemacs.
I've build something like this for some other project running
along much the same lines (one big SGML document split into many
partial SGML files and distributed across serveral directories).
I'm sure it can be adapted to the structures used here if there
is any interest. Well, is there??
2) The second paragraph is no longer valid. Maybe this was a problem
with older versions of psgml, but at least with current versions
of xemacs and psgml (I'm using xemacs-20.4 and psgml 1.2.0) it is
possible to make this work.
The inclusion of the local variable sgml-parent-document at the
end of all the .sgml files within the document tree leads me
to the conclusion, that this feature is already in use by the
maintainers and only the documentation has to be updated.
Maybe the wording of this paragraph should be changed to
something along the lines of the following text:
====== begin ===================================================
"It makes it more difficult for Emacs' sgml-mode to determine the
DTD to use, which it needs to provide it's useful benefits of
element completion, automatic validation and so on.
* Make sure the sgml-catalog-files variable contains the paths
to all necessary catalog files. It can be set by specifing the
environment variable SGML_CATALOG_FILES (see Example 3-6 and 3-7
in "3.2 Elements, tags, and attributes") or setting it directly
within your .emacs file.
Example: Setting sgml-catalog-files within .emacs
(setq sgml-catalog-files '(
"/usr/local/share/sgml/docbook/3.1/docbook.cat"
"/usr/local/share/sgml/jade/catalog"
"/usr/local/share/sgml/iso8879/catalog"
"/usr/src/doc/share/sgml/catalog"))
Note: This does not work if the specified catalog file contains
references to other catalog files via the CATALOG keyword.
Emacs' sgml-mode does not follow such references to find
the declarations of public entities.
* Specify sgml-parent-document as local variable within each
"partial" sgml file to provide a reference to Emacs' sgml-mode
where to look next for the missing DOCTYPE declaration. It is
possible to build a chain of multiple sgml files with the last
"top level" file containing the DOCTYPE declaration.
Put something like this at the end of the each partial sgml files:
Example: Use of local variable sgml-parent-document
<!--
Local Variables:
mode: sgml
sgml-parent-document: ("../book.sgml" "part" "chapter")
End:
-->
====== end =====================================================
>Release-Note:
>Audit-Trail:
>Unformatted:
To Unsubscribe: send mail to majordomo@FreeBSD.org
with "unsubscribe freebsd-doc" in the body of the message
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?200001291442.PAA00654>