Re: RFC: Changing of /doc/manuals/ implementation
On Mon, Sep 09, 2002 at 05:12:40PM +0200, Martin Schulze wrote:
> Rob Bradford wrote:
> > I'm proposing a new hierarchy for the /doc/manuals/ tree.
> >
> > There is currently some inconsistency, especially with the
> > quick-reference guide (osamu: i understand you are working on this, cool
> > =).
> >
> > My suggestion for the hierarchy is as follows:
> >
> > /doc/manuals/<lang>/<manual-name>/<format>/
>
> I wonder if you noticed that this will actually break content negotiation
> on the manuals?
AOL. That is the reason I have HTML pages of all languages in a
directory. If someone can set content negotiation to work with this
type of arrangement, it will be great.
This subject has been discussed previously without clear answer. Javier
complained about my arrangement but has not proposed alternatives. My
proposals made here address issues 1-5 (see below) and waiting for his
response (Hi, Javier!).
Here are issues to be concered.
1. Consistency between web(DDP), package(/usr/share/doc/)
2. Content negotiation for the web
3. Some OS does not work well with multiple extensions such as
reference.en.pdf
4. What should be the LANG choices (pt_BT, pt-br)
5. Bundling all text/pdf/ps file in one directory may not scale well.
6. How to handle CVS version vs. released version on the web.
7. Cleaner build script.
8. Consistency between other documents such as install manual and relese
notes.
Currently, following is my "consistency"
For web (debian-reference)
/doc/manuals/<doc-name>/*.<lang-web>.html
/doc/manuals/<doc-name>/examples/<files>
/doc/manuals/<locale>/<doc-name>.txt
/doc/manuals/<locale>/<doc-name>.ps
/doc/manuals/<locale>/<doc-name>.pdf
For package(debian-reference, apt-howto)
/usr/share/doc/Debian/<doc-name>/*.<lang-web>.html
/usr/share/doc/Debian/<doc-name>/examples/<files>
/usr/share/doc/Debian/<locale>/<doc-name>.txt
/usr/share/doc/Debian/<locale>/<doc-name>.ps
/usr/share/doc/Debian/<locale>/<doc-name>.pdf
<locale> is like : en, fr, it, pt_BR
<lang-web> is like : en, fr, it, pt-br
Alternative is, I think:
For web (debian-reference)
/doc/manuals/HTML/<doc-name>/*.<lang-web>.html
/doc/manuals/HTML/<doc-name>/examples/<files>
/doc/manuals/<locale>/<doc-name>.txt
/doc/manuals/<locale>/<doc-name>.ps
/doc/manuals/<locale>/<doc-name>.pdf
For package(debian-reference, apt-howto)
/usr/share/doc/Debian/HTML/<doc-name>/*.<lang-web>.html
/usr/share/doc/Debian/HTML/<doc-name>/examples/<files>
/usr/share/doc/Debian/<locale>/<doc-name>.txt
/usr/share/doc/Debian/<locale>/<doc-name>.ps
/usr/share/doc/Debian/<locale>/<doc-name>.pdf
Beside directory arrangement, I think extending current debiandoc-sgml
to create a language selection tab like other Debian web page may be
good idea.
--
~\^o^/~~~ ~\^.^/~~~ ~\^*^/~~~ ~\^_^/~~~ ~\^+^/~~~ ~\^:^/~~~ ~\^v^/~~~ +++++
Osamu Aoki @ Cupertino CA USA, GPG-key: A8061F32
.''`. Debian Reference: post-installation user's guide for non-developers
: :' : http://www.debian.org/doc/manuals/reference/ also http://qref.sf.net
`. `' "Our Priorities are Our Users and Free Software" --- Social Contract
Reply to: