Adam Di Carlo wrote: > > In article <[EMAIL PROTECTED]>, "James A. Treacy" <[EMAIL PROTECTED]> 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
