Summary of the html/info/webserver/whatever mess
Hi,
I will try to summarize what I did understand of the whole mess up to
now for my own mind's sanity (had to wade through all emails ;-)
Note that I won't include my own opinion (except where indicated), I
just want to summarize the technical and emotional points of view I
saw and I state my questions and conclusions. Note also that I left
out all these useless arguments like: more versatile, better base
format, browses nicely, accepted standard, etc.
Facts:
1. we started from a policy discussion about a documentation standard
for all debian packages
2. general documentation policy:
- it should be difficult to install a package without
documentation
- documentation policy regarding splitting should only apply
above a certain threshold (proposed 100k)
- it should be possible to install a package without
documentation
- documentation should be architecture independent so there is
only one documentation copy on the ftp site
- one should only have to download the documentation he wants
to install (say only info or only html or nothing at all)
!! Is here something missing ?
Proposed solutions:
I. split documentation in different packages (foo-doc-html,
foo-doc-info) which provide (foo-doc). foo suggests foo-doc.
Advantages:
+ meets all the mentioned criteria except perhaps the first one
+ possible with current tools
Disadvantages:
- more work for the maintainers regarding the splitting of packages
- increases package numbers, resulting in an even more cumbersome
packages list :-/
II. leaving documentation in the same package or at most one foo-doc
package
Advantages:
+ less work for the maintainers
+ hides documentation exclusion in the package tool (but this is
possible in the first approach either if the package tools are changed)
Disadvantages:
- doesn't satisfy the last three arguments of the list
- excluding not wanted documentation requires changes of package tools
!! Are there more solutions ?
3. from there the question of the default documentation format came up:
there are strong advocates of HTML and Info:
HTML:
++ images
++ easy to reformat
++ links over the net
++ no hard line breaks
-- uncompressed HTML is (much) larger than info docs (most mentioned point)
-- searching is done externally and there is no standard accepted way
of searching (yet) compared to info docs
-- no booklike hardcopy
Info:
++ searching is integrated
++ small
-- links out of the document are not (well) supported
-- not easy to reformat
-- no booklike hardcopy
Proposed solution: keeping both formats. Moving to HTML as default.
!! Should gzipped HTML be the default ? (I suppose most people will
answer here yes. That's why we got the webbrowser/webserver mud
throwing :-(
!! Suppose HTML is the default:
Questions:
- if different doc formats are available, only HTML should be
shipped ?
- if only latex, info, etc. are available, should they
be converted to HTML (how much effort is acceptable)
and again only HTML is shipped?
- if sgml or texi is available, should the sources be
shipped too ?
- should there be always a HTML and an info version,
if possible ?
- which documentation format do we encourage upstream?
- should the manpages format be included in these
considerations (man2html) ?
Assuming all these questions are decided on we can start the
webbrowser/webserver flame war :-(
IMHO the general documentation policy topic outlined above and the
preferred format topic are still not satisfying the proposed criteria.
We should work out these basics before discussing implementation.
[to Christian Schwarz: Sorry, that I brought the topic up again without
proposing better paragraphs, will try to work on a proposal in the
coming week]
BTW everybody calm down. It's only about documentation. If you want to
start flaming then take a more important topic like e.g. ice cream ;-)
Greetings,
Christian
--
Christian Meder, email: christian.meder@utoronto.ca
What's the railroad to me ?
I never go to see
Where it ends.
It fills a few hollows,
And makes banks for the swallows,
It sets the sand a-blowing,
And the blackberries a-growing.
(Henry David Thoreau)
--
TO UNSUBSCRIBE FROM THIS MAILING LIST: e-mail the word "unsubscribe" to
debian-devel-request@lists.debian.org .
Trouble? e-mail to templin@bucknell.edu .
Reply to: