Re: Documentation registry

[Taketoshi Sano <kgh12351@xxxxxxxxxxx>]

佐野＠浜松です。

 debian-policy@Org より、ドキュメントの登録についての話題。

In article <20000415205045.A3175@xxxxxxxxxxxxxx>,
  at "Sat, 15 Apr 2000 20:50:45 -0400',
   with "Documentation registry",
 Wichert Akkerman <wichert@xxxxxxxxxxxxxx> さん writes:

> [1  <text/plain; us-ascii (quoted-printable)>]
> 
> I've been thinking a bit about how documentation is registered
> in Debian currently, and it seems like we are doing it the wrong
> way. Currently there are a couple of ways to register documentation:
> 
> * call install-info
> * use a doc-base template and call install-docs
> * put a .dhelp file in the documentation-directory
> 
> I feel we should choose one single way to register documentation and use
> that for all packages. The current doc-base registry seems like a good
> way of doing it. However it has a couple of problems:
> 
> * the way it handles frontends like dhelp and dwww is broken, it needs to
>   do something more like update-menus does.
> * it doesn't handle translations
> 
> I think we should do something like this:
> * all packages register their documentation in a registration-file which
>   they insert in /usr/share/doc-registry/
> * the registrion-file lists the title, author, abstract and different
>   formats in which a document is available. It can lists this for
>   multiple languages if needed.
> * packages call a tool called update-docs in the postinst and postrm.
> * package which implement a frontend for documentations can put a
>   documentation method in /etc/doc-methods/.
> 
> For the format for the regstration file XML looks like a good strategy.
> Using its LANG-tag we can easily support multiple languages, we there
> are good XML parsers available for all scripting and most other
> languages. It would look something like this:
> 
> <doc>
>   <id>bzip2</id>
>   <author>
>     <name>Julian Seward</name>
>     <email>jseward@xxxxxxx</email>
>   </author>
>   <title>bzip and libzip2: a program and library for data compression</title>
>   <title lang=NL>bzip en libzip2: programma en routines for data
>                  compressie</title>
>   <section>apps/tools</section>
>   <format type=html>
>     <index>/usr/share/doc/libbz2/manul_toc.html</title>
>     <files>/usr/share/doc/libz2/manual_*.html</files>
>   </format>
>   <format type=postscript>
>     <index>/usr/share/doc/libbz2/manual.ps.gz</title>
>   </format>
>   <format type=postscript lang=NL>
>     <index>/usr/share/doc/libbz2/manual-nl.ps.gz</title>
>   </format>
>   <format type=texinfo>
>     <index>/usr/share/doc/libbz2/manual.texi.gz</title>
>   </format>
>   <format type=texinfo lang=NL>
>   <index>/usr/share/doc/libbz2/manual-nl.texi.gz</title>
>   </format>
> </doc>
> 
> Wichert.

複数のエンコーディングなファイルを single file にまとめるのは扱いが
面倒だから、現行の /usr/share/doc-base のように各パッケージ別にファイル
を分離したほうがいい、とか、あるいはどうしても single file にしたいなら
登録ファイルだけは Unicode にするべきでは、とかの反応があってもいいような。

タイトルや author は ASCII 文字に収まるとは限らないので。


-- 
     ＃ (わたしのおうちは浜松市、「夜のお菓子」で有名さ。)
    <kgh12351@xxxxxxxxxxx> : Taketoshi Sano (佐野　武俊)