Xfce documentation note (kind of long)

[Jannis Pohlmann]

Hey,

first of all, sorry for replying so late.

On Mon, 29 Jun 2009 14:12:29 -0500
Jim Campbell <jwcampbell at ubuntu.com> wrote:

(snipped the useful overview over the options we have)

> In short, I don't recommend DITA for a project of Xfce's size. It can
> do some powerful stuff if you're handling a lot of documentation, but
> it's overkill for a project like Xfce, and I think it would discourage
> new people from contributing.

Yeah, I get that feeling, too. The lack of open source tools for it
definitely is an issue. Also, it seems it's rarely used in open source
projects, hence no GTK+ viewers for it. Or am I wrong? I mean, we could
do pioneer work here, but we really lack the manpower for this.

> ReStructuredText+Sphinx would be ok if modularity wasn't an issue for
> Xfce. Even though translations aren't a big concern with Xfce, it
> would also be nice to accommodate them in a manner that's a little
> more advanced than copying and pasting.  rST+Sphinx isn't a bad
> option, though, and I could support using it for Xfce docs if people
> decided that is what is best.

I know that earlier I said we don't care so much about modularity and
we should just have one doc repository. After giving this more thought
I'd like to revoke that. We really want each component to install its
own docs, otherwise we'd violate one of the key concepts of Xfce:
modularity. I mean, we could have one repository and use git submodules
and thelike to include the individual docs in the different tarballs,
but for that the documentation system has support this.

I still think Sphinx isn't capable of that. You have one big reST
tree, you install it and you're done. Doc pages are linked to each
other and stuff. But what if different components contribute separate
documentation parts and you still want them to be linked in some
intelligent way? 

Christopher told us Sphinx can do this, but he didn't seem to be able
to elaborate on that more. So for now I assume this kind of scenario is
unsupported.

> Mallard seems like the best overall compromise to me, though, even if
> it isn't fully ready yet.  I've been closely involved with the GNOME
> doc team on the project, and they're interested in working to develop
> a cross-platform doc solution, and Mallard offers an xml-based syntax
> that isn't too complicated. Also, within a year or so, it would be
> able to accommodate the modularity of Xfce (something not possible
> with rST+Sphinx), and it offers some neat features with regards to
> recursive linking.

Yes, so far Mallard looks most promising, despite it's early stage. If
it's easy to write a doc viewer on top of a future "libyelp" with
reasonable dependencies, let's do it. Also, Mike tested translating
docbook documentation using .po files and he seemed to be pleased with
this translation workflow, even for longer texts. That clearly speaks
for an XML-based approach that makes it easier for the docs to be
translated.

The question is: do we have any short-term solution? Mallard seems a
bit far away at the moment. 
 
> That's all I have on the subject for now, though.  Please let me know
> what you think, and if you have any major concerns or additional
> thoughts at this point.  Also, if you feel strongly about one approach
> or another, please feel free to share it.  Thanks very much.

Thanks again for your investigations, Jim!

  - 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/20090707/5cf2197e/attachment.pgp>