Re: doc directory of the web pages
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.
Reply to: