Re: doc directory of the web pages
Adam Di Carlo wrote:
>
> In article <19981129155146.D10057@debian.org>, "James A. Treacy" <treacy@debian.org> writes:
>
> > At a minimum, use of index.html should be recommended. I suggest
> > that it be required.
>
> Agreed.
Yes, there should be uniform launch point, whatever the structure
otherwise. Should this exist in all cases, e.g. be link to some
dummy page?
> > 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.
Some packages may have several documents. (I seen some, with *big*
ones.)
This should be possible, but not recommended unless there are
really many
files.
> > 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.
May be multiple documents. Does not rule out short subdir names
tho',
html/ should be default, I think.
> > 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
What about our packages then, where should this info go so that
Debian packaged servers are guaranteed to recognize this out of
the box?
> 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.
I am. I have seen packages with *lots* of files. No need to limit
structure of packages, even _documentation_ packages this way.
If there are multiple documents, each in its own subdir, they are
all referenced from index.html
> > * 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.
server configuration, I presume
> > 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> ?
Hint for the browser packagers? Policy even?
t.aa
Reply to: