Documentation proposal

[Jannis Pohlmann]

On Mon, 04 May 2009 11:35:31 +0200
Jérôme Guelfucci <jerome.guelfucci at gmail.com> wrote:

> Nick Schermer:
> > 2009/5/4 Jannis Pohlmann <jannis at xfce.org>:
> >   
> >> On Mon, 4 May 2009 10:49:07 +0200
> >> Nick Schermer <nickschermer at gmail.com> wrote:
> >>
> >>     
> >>> 2009/5/4 Jannis Pohlmann <jannis at xfce.org>:
> >>>       
> >>>> I'm against too complex hooks. I also have the feeling that the
> >>>> good old gettext translation method is not really suited for
> >>>> continuous text. IMHO the little syntax overhead you have with
> >>>> reST makes .po files almost pointless.
> >>>>         
> >>> The point is tracking changes. The advantage of po files it will
> >>> result in fuzzy or untranslated strings, for separate files you
> >>> have to compare it with the original version. The syntax overhead
> >>> is not the point, keeping in sync is.
> >>>       
> >> I've just read Mike's mail on xfce-i18n. If translators feel that
> >> they are more comfortable with rst2xml + xml2po + xml2rst rather
> >> than translating the docs by creating a copy of the original
> >> english docs, that's fine with me. I'm not (really) a translator
> >> so I'm not in the position to make this decision - translators
> >> should decide here. 
> >
> > >From this point I think we make it too complicated. Why not put all
> > the docs in 1 git module, use docbook + xml2po for translations
> > (translations also in the docs module) and hooks or submodules to
> > link the docs to the core modules.
> > We could provide some extra scripts in the docs module to make this
> > easier and automate some stuff.
> >
> > reST simply does not quite suit our needs IMHO, we could use it and
> > work around all the problems, but that will result in more
> > maintenance. Docbook is a bit rough on the edges, but it works fine
> > (proven concept) and there are a lot of (good) tools for translators
> > and developers.
> >
> > Nick
> > _______________________________________________
> > Xfce4-dev mailing list
> > Xfce4-dev at xfce.org
> > http://foo-projects.org/mailman/listinfo/xfce4-dev
> >
> >   
> Hello,
> 
> I think we should take into account who is going to write the 
> documentation: docbook may be 100% fine for developpers but it's
> really unfriendly. During the 4.6 cycle I contributed to the
> xfdesktop documentation and I can tell that docbook is really a pain
> for newcomers and that it could deter some potential contributors.
> 
> Moreover I do not think the GUI items thing of docbook are crucial, 
> currently we have an almost 100% outdated documentation. I think most 
> users won't care if the new documentation does not look as polished
> as before, they want something that can help them. If rest can help 
> improving the contents, it's definately a positive point that should
> be taken into account.

Agreed. Special GUI markup is something we could add if we really need
it but I don't think it's *that* important.

  - Jannis
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 197 bytes
Desc: not available
URL: <http://mail.xfce.org/pipermail/xfce4-dev/attachments/20090504/4cefe677/attachment.pgp>