Documentation proposal

[Jannis Pohlmann]

On Sat, 23 May 2009 12:03:04 -0500
Jim Campbell <jwcampbell at ubuntu.com> wrote:

> Hi All,
> 
> Just wanted to put in a short note that I've been able to make an
> initial effort to draft up some documentation for Xfce using
> reStructuredText and Sphinx. I've attached a sample of my work to
> this message, so please let me know if it doesn't come through on the
> mailing list.
> 
> The sample includes some introductory text and images from the Thunar
> documentation currently on the web. There are actually two .rst files
> included, as I wanted to test out cross-document linking.  I didn't
> do a complete run-through of the Thunar docs, but the built-out html
> files are located in the _build/html folder; please start with the
> index.html file.
> 
> It also looks like we can include something similar to docbook's
> "entities" to assist with various items that get repeated throughout
> the documentation. For example, this might include program names,
> gui-button paths (i.e., File
> > Save As . . . ), and other relevant variables.  I didn't include
> > such a
> feature in this set of docs.
> 
> In addition to all of this, I'm going to an open-source doc
> conference in a few weeks, and one of the presenters is going to talk
> about pydocweb ( http://www.ohloh.net/p/pydocweb ), so that may even
> assist us as a web-based editor for all of this?  I'll have more info
> later, but pydocweb does integrate with Sphinx.

Sounds cool, keep us posted.

> The main thing for me right now would concern the translations. The
> syntax seems workable, the output looks fine (and can be themed to
> suit Xfce) . . . if people are ok with just allowing straight
> translations from the source files, then I wouldn't see anything that
> would hold it back.

Thanks Jim.

I'll be experimenting with the xfce4-docs repository layout and git
submodules next week while I'm in Barcelona with Stephan. If all goes
well we'll have things set up by the end of the week.

I think I've made my point about the translations pretty clear. If
there are no further objections, this is the way we'll do it.

  - 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/20090523/c7a5bc5e/attachment.pgp>