In article <[EMAIL PROTECTED]>, "James A. Treacy" <[EMAIL PROTECTED]> 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 [EMAIL PROTECTED]<URL:http://www.onShore.com/>
