Re: doc directory of the web pages
In article <[🔎] 19981129155146.D10057@debian.org>, "James A. Treacy" <treacy@debian.org> writes:
> 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> .
Ok, right. It's all consistent and the same.
> At a minimum, use of index.html should be recommended. I suggest
> that it be required.
Agreed.
> 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/ .
No, I don't like that and it wouldn't do that. That's for the build
area, not the installled area. Adds another level of dirs and it's
unnecessary, IMHO.
> 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.
Yes, I think so.
> 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.
Why not go further:
/usr/doc/<package>/index.html
Period. Any symlinks (or not, great) the package maintainer can work
out.
Some might not like all the HTML right in /usr/doc/<package>/, but I
am not one of those some.
> * 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)
Yes, also, http://www.debian.org/doc/<package>/index.html must work.
> 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.
This is better, I take it.
> 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.
We're going to need to do some work to get this into place.
Theoretically, I don't see why we can't exploit the content
negotiation stuff... it might take a few revs of debiandoc-sgml to get
there. I.e., we're talking live for Feb by the earliest I think.
> 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> ?
Argh. I don't like inconsistency at all. It's a big PITA. Why can
we just keep it consistent? People only need to know about
index.de.html if it exists. Maybe it's clutter, but so what?
> 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.
Like it so far.
> BTW, we seem in agreement about everything else.
Cool.
> (*)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.
Probably.
--
.....Adam Di Carlo....adam@onShore.com.....<URL:http://www.onShore.com/>
Reply to: