[Date Prev][Date Next] [Thread Prev][Thread Next] [Date Index] [Thread Index]

Summary of the html/info/webserver/whatever mess


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.


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 policy regarding splitting should only apply
	  above a certain threshold (proposed 100k) 
	- it should be possible to install a package without
	- 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. 

+ meets all the mentioned criteria except perhaps the first one
+ possible with current tools

- 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

+ 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)

- 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:

++ 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

++ 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:
		- 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 ;-)



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: