Re: [Bug-gnulib] html/doc target in coding standards

[Bruno Haible]

Karl Berry wrote:
>     What program do you assume people use for "viewing" XML documentation?
>
> I don't assume anything.  I just felt like there should be the
> possibility of having the documentation in some XML form available, ...

>  |     is XML really used as installed documentation?  
>  | 
>  | It can be.  You can view XML files directly in mozilla (and
>  | other browsers, I suppose).  You're right that it's usually
>  | used as a basis for further transformations, but even then, I
>  | don't see a reason not to install it -- could be useful to
>  | have it there for that purpose.  And finally, not treating it
>  | like the others will be huge source of confusion, I feel
>  | sure.

These are assumptions that don't match the facts.

1) None of leading free browsers can display something reasonable when
pointed to an XML file.

For a test I used "makeinfo --docbook cln.texi" and "makeinfo --xml cln.texi"
and pointed the browsers to cln.xml.

  * konqueror 3 opens a text editor window for the XML file.

  * mozilla 1.5 and galeon display an error window

    - for --docbook:
      XML Parsing Error: undefined entity
      Location: file:///tmp/cln.xml
      Line Number 61, Column 1:&lsquo;<literal>CLN</literal>&rsquo; another 
meaning: it becomes an abbreviation of

    - for --xml:
      XML Parsing Error: undefined entity
      Location: file:///tmp/cln.xml
      Line Number 17, Column 21:    <para>Copyright &copyright; Bruno Haible 
1995, 1996, 1997, 1998, 1999, 2000, 2001.</para>

    - When an XML file without entities is used:
      "This XML file does not appear to have any style information associated
       with it. The document tree is shown below."
      and then it shows the XML in textual form with tree widget interactions
      enabled.

So, as it stands, these XML files cannot be viewed immediately by a user.

2) When using these XML files as "basis for further transformations", the
user will need
  * an XSLT processor installed (not usually part of a normal Unix
    installation),
  * special processing instructions. For example, to convert clisp's
    XML to HTML, you need to execute the command
       "xsltproc --stringparam target.database.document olink-pile.xml 
--stringparam current.docid impnotes -o impnotes.html pile.xsl impnotes.xml"

I don't think that this will become easy-to-use and commonplace soon.


For these reasons, I think it will be more confusing for most users if
*.xml files are installed under $(datadir)/doc/$(PACKAGE)/, than it will
be useful for the few users who know how to do something with XSLT.

I therefore object to 'xmldir' and --xmldir, and propose that packages
who wish to install their XML documentation do so under
$(datadir)/$(PACKAGE)/, not $(datadir)/doc/$(PACKAGE)/.

Bruno