[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: [Bug-gnulib] html/doc target in coding standards
From: |
Bruno Haible |
Subject: |
Re: [Bug-gnulib] html/doc target in coding standards |
Date: |
Tue, 12 Oct 2004 14:39:06 +0200 |
User-agent: |
KMail/1.5 |
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:‘<literal>CLN</literal>’ 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 ©right; 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