On Sun, Nov 29, 1998 at 01:16:12AM -0500, Adam Di Carlo wrote: > * install the package and get /usr/doc/<package>/<package>.html > (wouldn't /usr/doc/<package>/index.html be better?) > > * also find it at http://www.debian.org/<package>/<package>.html > (wouldn't http://www.debian.org/<package>/index.html be better?) > * find devel copy at <DDP-ROOT>/<package>/<package.html > (ditto) > You missed the copy of many docs that sit in the ftp archive (*). Under this scheme they would simply go in archive_root/doc/<package> .
At a minimum, use of index.html should be recommended. I suggest that it be required. Note that a lot of packages currently put the html in a subdir (since you didn't give an ending '/' above it is not clear whether you intended this or not). For example, /usr/doc/developers-reference/developers-reference.html/ . It doesn't matter to me whether the html goes in a subdirectory or not. Using a subdirectory reduces clutter, but it would be nice to view http://localhost/doc/<package>/ and get the html right away. If we go with subdirectories, I would prefer a subdirectory with a shorter name though, eg /usr/doc/developers-reference/html/ . We already know what document the html is about. For /usr/doc/, we could even have index.html in the main directory with the rest of the html in a subdirectory. Thus, I'm suggesting: * /usr/doc/<package>/index.html -> html/ /usr/doc/<package>/html/*.html If there is only one file, /usr/doc/<package>/index.html could contain the actual file. * http://www.debian.org/doc/<package>/*.html (for consistency, this is done even if the document contains only one file. If it is later broken into multiple pages, no changes are required) * <DDP-ROOT>/<package>/ * archive_root/doc/<package>/*.html (is it necessary to have other versions, like .txt or .ps, in the archive? Or as discussed below, are ANY of the docs needed in the archive?) As many people may not be aware of the issues involved in serving multiple languages in html, I'll give a summary. Simply keep different languages in different directories. Obvious and simple. Links must be made to every language. Keep different languages in the same directory and let the server 'negotiate' with the client which to deliver. This is what is used on the Debian web pages. It requires files to be in the form <file>.<lang>.html, links to directories should stop at the '/' (common practice anyway) and links should only give the basename of the file, e.g. 'ch-alternatives' instead of 'ch-alternatives.html'. This allows content negotiation to work. If is too difficult for you to generate tags like this, then different languages will need to go in different directories and we'll need to add seperate links for each version. We'll also need to decide on a convention for naming the subdirs. Since you know the capabilities the DTD used, the debian-doc crew will have to decide which way to go. I wouldn't recommend the content negotiation (CN) approach for the /usr/doc directory since most users will not enable CN in their browser. Guess we'll need to come up with a convention for that anyway. How about html.<lang> ? This is getting longer than I intended. Instead of trying to enumerate every possibility, tell me what you think so far and we can then fill in any missing details. BTW, we seem in agreement about everything else. Jay Treacy (*)It makes more sense for documentation to be on the web site: the archive contains packages and the web site contains documentation. On the other hand, there is something to be said to having everything needed to install Debian available in one place. Thus, I would suggest that the only documentation that belongs in the archive is the installation manual.
