Re: [docbook] links within classsynopsis?

[Michael Smith <smith@xml-doc.org>]

Hi Stephen,

[Cc'ing the docbook list so we can keep the discussion there.]

> Thanks.  The ENTITY trick works, with the cvs version of synop.xml.  
> Emacs's xml mode doesn't like it when I try to put a <link> inside a  
> <methodname>,

Which mode is that, exactly? If you type "C-h m", what does it say?

It if says "nXML mode: Major mode for editing XML.", then it is
actually doing validation using an RELAX NG grammar for DocBook,
and not a DTD. And it doesn't consider the internal DTD subset in
the DOCTYPE in your doc instances at all when doing validation.

But if it says "XML mode: Major mode for editing XML, specialized
from SGML mode. Sets various variables appropriately for XML.",
then it is the "other" Emacs XML/SGML mode -- PSGML (which is
with the actually mode name being "xml-mode" and/or "sgml-mode"
and/or "psgml-mode", depending on how it's configured on your
system). That mode does in fact read the internal subset and
should not complain about the <link>.

You can toggle between the modes by doing "M-x nxml-mode" and
"M-x xml-mode" (or maybe "M-x sgml-mode" or "M-x psgml-mode"). If
you are PSGML, you should be able to validate your doc using
PSGML's internal parser by doing "C-c C-p" (sgml-load-doctype) and
then "C-c C-o" (sgml-next-trouble-spot).

> but I can live with that, or learn about DTD  customization
> layers.

I think rather than that, you are better off using nXML (as you
seem to be, if you're getting that <link> instance flagged as an
error), and creating a RELAX NG customization layer.

You can do that in a couple of steps.

1. In nxml-mode, do "C-c C-s C-w" (rng-what-schema). That will
   give you the pathname on your system to the file (docbook.rnc
   file) that nXML is using to validate your DocBook documents. On
   my Debian system, that file gets installed in:

     /usr/share/emacs/site-lisp/nxml-mode/schema/docbook.rnc

2. Create a file named "custom.rnc" (or whatever) and put the
   following into it.

     include "/usr/share/emacs/site-lisp/nxml-mode/schema/docbook.rnc" {
        local.smallcptr.char.mix = link
     }

3. To validate your documents, do "C-c C-s C-f"
   (rng-set-schema-file-and-validate) and type or paste in the
   pathname to your "custom.rnc" file.

   To have your custom.rnc file always used automatically instead
   of the standard docbook.rnc file, you need to either edit the
   system "schemas.xml" file, or create a custom one and configure
   nXML to use that. In Debian, the system schemas.xml file is in:

     /usr/share/emacs/site-lisp/nxml-mode/schema/schemas.xml

   You would need to change the  <typeId id="DocBook"... line to:

     <typeId id="DocBook" uri="~/custom.rnc"/>

   Or whatever the path to you custom.rnc file actually is.

Hope that helps,

  --Mike

-- 
Michael Smith
http://sideshowbarker.net/

smime.p7s