Re: Manual with several architectures together (Was: Hardcopy documentation

[Adam Di Carlo <adam@onshore.com>]

>This is because the installation manual uses conditional sections,
>no? And no SGML parser can use them that way (some are included, some
>are ignored but there is no way, above the parser, to know why or why
>not they were included).

Yes, though this is a rather perverse formulation.  I would say that
parameters set by the authors control what text is included or not in
the document.  It's true the parser/validator is ignorant of such
facts, but since I have ready means of producing "flavors" for all
architectures, then all *actual* permutations are readily tested.

For instance, I have sections which are specific to one architecture,
and which will only be included when I'm building for that
architecture.  But in many many cases, I have sections which are
specific to a given capability, for instance:
  <![ %i386    [ <!ENTITY % supports-bootable-cd "INCLUDE"> ]]>
                 <!ENTITY % supports-bootable-cd "IGNORE">

I have text which talks about workarounds for a given bug:
  <![ %i386  [ <!entity % workaround-bug-31315 "INCLUDE"> ]]>
               <!entity % workaround-bug-31315 "IGNORE">
When the bug is fixed I just either remove it from the source text or
unconditionally set it to IGNORE.

I have text which is temporary and should only be on rough drafts;
that stuff I put inside '%FIXME' marked sections.

>Therefore, I prefer the method to use attributes with values
>(arch="i386") which makes easy in the stylesheet to keep only one
>arch, or to keep them all, and adding the name "with bracketed
>per-architecture notes".

Given that you prefer XML, of course you have to say this, since XML
doesn't have marked sections.

I've hear arguments why you should do things in the style level, but
these are purely vapor -- I've never seen a working implementation,
XML or SGML.

Moreover, I'm using Debiandoc-SGML, so there are no stylesheets, no
applicable attributes, and no real means providing for customizing
either one.  I could move to DocBook but at this point, one has to
wonder whether one is more deeply committed to quality of
documentation or the ideality of markup/formatter system.

.....Adam Di Carlo....adam@onShore.com.....<URL:http://www.onShore.com/>