Bug#175770: dpkg-dev: dpkg-scansources man page "prog"

[Martin Quinson <Martin.Quinson@tuxfamily.org>]

On Thu, Jan 16, 2003 at 11:10:45AM +0100, Wichert Akkerman wrote:
> Previously Martin Quinson wrote:
> > tag 175770 patch
> > thanks
> 
> Imho the real fix is to remove the manpage from the perl-script anyway.
> Merging user documentation and code in a single file is not a very good
> idea imho and makes it harder for translators.

You're the boss, but I strongly disagree here.

I think that putting the documentation along the code is the a very good
solution to get developpers documenting their changes.

Moreover, it's really not a problem for translators, since they can use
po4a (done by your servitor et al ;) to translate it.

>From http://savannah.nongnu.org/projects/po4a :

  The goal of the po4a (po for anything) project is to ease the work of free
  software translators. For now, their work is quite easy for program
  messages (thanks to po files and gettext), but nothing similar exist for
  documentation.

  The goal of the project is to develop small programs and scripts to
  extract the text which should be translated from where it is, put it in po
  files, and then, when the translators are done, reinject their work in the
  structure of the document.

  Using po files make it easy to track changes in the original document,
  without actually having to retranslate anything.

  A whole bunch of modules is available:
    - KernelHelp: The help messages associated with each kernel compilation 
      option.
    - Man: Good old manual page format.
    - Pod: Perl documentation format.
    - Sgml: either debiandoc or docbook DTD.

  We are thinking about other modules, like wml (web meta language),
  texinfo, XML, HTML and others.

  The project is somehow related to gettext (of course), poxml (a tool
  developped by KDE to do what we want for DocBook XML files), and intltools
  (a tool develloped by the Gnome guys to do that for .desktop files, and
  glade interfaces).

So, translating pod documentation is as easy as translating man pages (or
even easier), and pod is far simpler to write for programmers, which is
another argument for saying that pod documentation is potentially better
maintained...

Thanks, Mt.

-- 
Nos péchés sont têtus, nos repentirs sont lâches
          --- Ch.Baudelaire, Les fleurs du mal