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

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: