RE: Where, what and how - The future of DocBook

RE: Where, what and how - The future of DocBook

[Peter Ring]

Put this at the bottom of your XML files:

<!-- Keep this comment near the end of the file
Local variables:
mode: xml
sgml-declaration: "xhtml1.dcl"
End:
-->

Replace "xhtml1.dcl" with the pathname of the correct declaration, e.g.,
"/usr/lib/sgml/declaration/xml.dcl".

Kind regards
Peter Ring


-----Original Message-----
From: Mark Johnson [ mailto:mark@phy.duke.edu ]
Sent: 6. december 2000 17:05
To: docbook-tools-discuss@sourceware.cygnus.com
Subject: Re: Where, what and how - The future of DocBook

...

You might want to add that validation requires the XML declaration (xml.dcl
or xml.decl) rather than docbook.dcl.

In your .emacs you may have something like:

    (setq sgml-declaration "/usr/lib/sgml/declaration/docbook.dcl")

For XML I tried the following, but for some reason it doesn't work:

    (setq sgml-xml-declaration "/usr/lib/sgml/declaration/xml.dcl")

...

More psgml tips...

[Mark Johnson]

> Put this at the bottom of your XML files:
>
> <!-- Keep this comment near the end of the file
> Local variables:
> mode: xml
> sgml-declaration: "xhtml1.dcl"
> End:
> -->
>

Thanks for the tip. I never thought to do that.

It'd be nice if when in xml-mode psgml used xml.dcl, and a different one when
in sgml-mode. Does anyone know if/how I can tweak my .emacs so emacs will use
different declarations according to the mode--sgml or xml?

As long as we're talking local-variables and passing tips for good
documentation, one of my faves is using the sgml-parent-document variable.

Setting this variable allows you to edit the various sub-files that compose a
larger document without having to insert a DOCTYPE statement at the top of
them. And to do it in a dtd-aware fashion.

Put another way, there's no need to put a DOCTYPE statement in the chapter
files of a book while editing them.

The problem I had was that I couldn't understand the explanation in the psgml
docs telling me how to do it.  I think I finally learned from a post on this
or docbook-apps. Most subscribers probably know this, but I'll explain how to
do it for those who don't.

Here's an example:

    Parent file = mybook.xml
    Root element of parent file = <book>

    Child file = chapter2.xml file
    Root element of child file = <chapter>

put the following at the bottom:
    <!--
    Local variables:
    mode: xml
    sgml-parent-document:("mybook.xml" "book" "chapter")
    End:
    -->

the general pattern that works for me is:

    sgml-parent-document:("parent-filename" "root-element-of-parent-file"
"root-element-of-current-file")

Which I think is easier to understand than the full psgml explanation. On
first encounter, anyway. Here's the psgml explanation:

------------------------------------------------
Documentation:
* Used when the current file is part of a bigger document.

The variable describes how the current file's content fit into the element
hierarchy. The variable should have the form

  (PARENT-FILE CONTEXT-ELEMENT* TOP-ELEMENT (HAS-SEEN-ELEMENT*)?)

PARENT-FILE is a string, the name of the file contatining the
  document entity.
CONTEXT-ELEMENT is a string, that is the name of an element type.
  It can occur 0 or more times and is used to set up
  exceptions and short reference map. Good candidates
  for these elements are the elements open when the
  entity pointing to the current file is used.
TOP-ELEMENT is a string that is the name of the element type
  of the top level element in the current file. The file
  should contain one instance of this element, unless
  the last (lisp) element of sgml-parent-document is a
  list. If it is a list, the top level of the file
  should follow the content model of top-element.
HAS-SEEN-ELEMENT is a string that is the name of an element type. This
         element is satisfied in the content model of top-element.

Setting this variable automatically makes it local to the current buffer.
-------------------------------------------------

Of course now I understand the explanation above. What's that saying about
hindsight?

Cheers,
Mark

>
> Replace "xhtml1.dcl" with the pathname of the correct declaration, e.g.,
> "/usr/lib/sgml/declaration/xml.dcl".
>
> Kind regards
> Peter Ring
>
> -----Original Message-----
> From: Mark Johnson [ mailto:mark@phy.duke.edu ]
> Sent: 6. december 2000 17:05
> To: docbook-tools-discuss@sourceware.cygnus.com
> Subject: Re: Where, what and how - The future of DocBook
>
> ...
>
> You might want to add that validation requires the XML declaration (xml.dcl
> or xml.decl) rather than docbook.dcl.
>
> In your .emacs you may have something like:
>
>     (setq sgml-declaration "/usr/lib/sgml/declaration/docbook.dcl")
>
> For XML I tried the following, but for some reason it doesn't work:
>
>     (setq sgml-xml-declaration "/usr/lib/sgml/declaration/xml.dcl")
>
> ...

Re: More psgml tips...

[Michael Wiedmann]

Mark Johnson wrote:
...
> Setting this variable allows you to edit the various sub-files that compose a
> larger document without having to insert a DOCTYPE statement at the top of
> them. And to do it in a dtd-aware fashion.
... 
> Here's an example:
> 
>     Parent file = mybook.xml
>     Root element of parent file = <book>
> 
>     Child file = chapter2.xml file
>     Root element of child file = <chapter>
> 
> put the following at the bottom:
>     <!--
>     Local variables:
>     mode: xml
>     sgml-parent-document:("mybook.xml" "book" "chapter")
>     End:
>     -->

Good tip, Mark!

Translated to a "website" document this would mean:

<!--
Local variables:
mode: xml
sgml-parent-document:("myfile.xml" "website" "webpage")
End:
-->

Correct?

Michael
-- 
office:  michael.wiedmann@detewe.de
private: mw@miwie.in-berlin.de                 http://www.miwie.org/
         mw@miwie.org                          http://wap.miwie.org/

More psgml tips...

[Mark Johnson]

> Put this at the bottom of your XML files:
>
> <!-- Keep this comment near the end of the file
> Local variables:
> mode: xml
> sgml-declaration: "xhtml1.dcl"
> End:
> -->
>

Thanks for the tip. I never thought to do that.

It'd be nice if when in xml-mode psgml used xml.dcl, and a different one when
in sgml-mode. Does anyone know if/how I can tweak my .emacs so emacs will use
different declarations according to the mode--sgml or xml?

As long as we're talking local-variables and passing tips for good
documentation, one of my faves is using the sgml-parent-document variable.

Setting this variable allows you to edit the various sub-files that compose a
larger document without having to insert a DOCTYPE statement at the top of
them. And to do it in a dtd-aware fashion.

Put another way, there's no need to put a DOCTYPE statement in the chapter
files of a book while editing them.

The problem I had was that I couldn't understand the explanation in the psgml
docs telling me how to do it.  I think I finally learned from a post on this
or docbook-apps. Most subscribers probably know this, but I'll explain how to
do it for those who don't.

Here's an example:

    Parent file = mybook.xml
    Root element of parent file = <book>

    Child file = chapter2.xml file
    Root element of child file = <chapter>

put the following at the bottom:
    <!--
    Local variables:
    mode: xml
    sgml-parent-document:("mybook.xml" "book" "chapter")
    End:
    -->

the general pattern that works for me is:

    sgml-parent-document:("parent-filename" "root-element-of-parent-file"
"root-element-of-current-file")

Which I think is easier to understand than the full psgml explanation. On
first encounter, anyway. Here's the psgml explanation:

------------------------------------------------
Documentation:
* Used when the current file is part of a bigger document.

The variable describes how the current file's content fit into the element
hierarchy. The variable should have the form

  (PARENT-FILE CONTEXT-ELEMENT* TOP-ELEMENT (HAS-SEEN-ELEMENT*)?)

PARENT-FILE is a string, the name of the file contatining the
  document entity.
CONTEXT-ELEMENT is a string, that is the name of an element type.
  It can occur 0 or more times and is used to set up
  exceptions and short reference map. Good candidates
  for these elements are the elements open when the
  entity pointing to the current file is used.
TOP-ELEMENT is a string that is the name of the element type
  of the top level element in the current file. The file
  should contain one instance of this element, unless
  the last (lisp) element of sgml-parent-document is a
  list. If it is a list, the top level of the file
  should follow the content model of top-element.
HAS-SEEN-ELEMENT is a string that is the name of an element type. This
         element is satisfied in the content model of top-element.

Setting this variable automatically makes it local to the current buffer.
-------------------------------------------------

Of course now I understand the explanation above. What's that saying about
hindsight?

Cheers,
Mark

>
> Replace "xhtml1.dcl" with the pathname of the correct declaration, e.g.,
> "/usr/lib/sgml/declaration/xml.dcl".
>
> Kind regards
> Peter Ring
>
> -----Original Message-----
> From: Mark Johnson [ mailto:mark@phy.duke.edu ]
> Sent: 6. december 2000 17:05
> To: docbook-tools-discuss@sourceware.cygnus.com
> Subject: Re: Where, what and how - The future of DocBook
>
> ...
>
> You might want to add that validation requires the XML declaration (xml.dcl
> or xml.decl) rather than docbook.dcl.
>
> In your .emacs you may have something like:
>
>     (setq sgml-declaration "/usr/lib/sgml/declaration/docbook.dcl")
>
> For XML I tried the following, but for some reason it doesn't work:
>
>     (setq sgml-xml-declaration "/usr/lib/sgml/declaration/xml.dcl")
>
> ...

RE: Where, what and how - The future of DocBook

[Peter Ring]

Put this at the bottom of your XML files:

<!-- Keep this comment near the end of the file
Local variables:
mode: xml
sgml-declaration: "xhtml1.dcl"
End:
-->

Replace "xhtml1.dcl" with the pathname of the correct declaration, e.g.,
"/usr/lib/sgml/declaration/xml.dcl".

Kind regards
Peter Ring


-----Original Message-----
From: Mark Johnson [ mailto:mark@phy.duke.edu ]
Sent: 6. december 2000 17:05
To: docbook-tools-discuss@sourceware.cygnus.com
Subject: Re: Where, what and how - The future of DocBook

...

You might want to add that validation requires the XML declaration (xml.dcl
or xml.decl) rather than docbook.dcl.

In your .emacs you may have something like:

    (setq sgml-declaration "/usr/lib/sgml/declaration/docbook.dcl")

For XML I tried the following, but for some reason it doesn't work:

    (setq sgml-xml-declaration "/usr/lib/sgml/declaration/xml.dcl")

...

Re: More psgml tips...

[Michael Wiedmann]

Mark Johnson wrote:
...
> Setting this variable allows you to edit the various sub-files that compose a
> larger document without having to insert a DOCTYPE statement at the top of
> them. And to do it in a dtd-aware fashion.
... 
> Here's an example:
> 
>     Parent file = mybook.xml
>     Root element of parent file = <book>
> 
>     Child file = chapter2.xml file
>     Root element of child file = <chapter>
> 
> put the following at the bottom:
>     <!--
>     Local variables:
>     mode: xml
>     sgml-parent-document:("mybook.xml" "book" "chapter")
>     End:
>     -->

Good tip, Mark!

Translated to a "website" document this would mean:

<!--
Local variables:
mode: xml
sgml-parent-document:("myfile.xml" "website" "webpage")
End:
-->

Correct?

Michael
-- 
office:  michael.wiedmann@detewe.de
private: mw@miwie.in-berlin.de                 http://www.miwie.org/
         mw@miwie.org                          http://wap.miwie.org/