From owner-freebsd-doc Sat Jan 29 6:50: 8 2000 Delivered-To: freebsd-doc@freebsd.org Received: from freefall.freebsd.org (freefall.FreeBSD.ORG [204.216.27.21]) by hub.freebsd.org (Postfix) with ESMTP id C831B155F9 for ; Sat, 29 Jan 2000 06:50:03 -0800 (PST) (envelope-from gnats@FreeBSD.org) Received: (from gnats@localhost) by freefall.freebsd.org (8.9.3/8.9.2) id GAA76325; Sat, 29 Jan 2000 06:50:03 -0800 (PST) (envelope-from gnats@FreeBSD.org) Received: from mailout06.sul.t-online.de (mailout06.sul.t-online.de [194.25.134.19]) by hub.freebsd.org (Postfix) with ESMTP id 8F11F16278 for ; Sat, 29 Jan 2000 06:42:11 -0800 (PST) (envelope-from Karlheinz.Eckmeier@t-online.de) Received: from fwd06.sul.t-online.de by mailout06.sul.t-online.de with smtp id 12EZ4k-0007x1-00; Sat, 29 Jan 2000 15:42:10 +0100 Received: from abakus.my.domain (09064958-0001@[62.158.61.204]) by fwd06.sul.t-online.de with esmtp id 12EZ4c-0WyDZoC; Sat, 29 Jan 2000 15:42:02 +0100 Received: (from khe@localhost) by abakus.my.domain (8.9.3/8.9.3) id PAA00654; Sat, 29 Jan 2000 15:42:15 +0100 (CET) (envelope-from khe) Message-Id: <200001291442.PAA00654@abakus.my.domain> Date: Sat, 29 Jan 2000 15:42:15 +0100 (CET) From: Karlheinz.Eckmeier@t-online.de Reply-To: Karlheinz.Eckmeier@t-online.de To: FreeBSD-gnats-submit@freebsd.org X-Send-Pr-Version: 3.2 Subject: docs/16439: fdp-primer - difficulties with split SGML files Sender: owner-freebsd-doc@FreeBSD.ORG Precedence: bulk X-Loop: FreeBSD.org >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: 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). >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, ,). 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 ====== end ===================================================== >Release-Note: >Audit-Trail: >Unformatted: To Unsubscribe: send mail to majordomo@FreeBSD.org with "unsubscribe freebsd-doc" in the body of the message