Re: [Gnewsense-dev] Organizing wiki documentation by version

[Sam Geeraerts]

Op Sat, 17 Aug 2013 16:51:02 -0500
schreef Felipe Lopez <address@hidden>:

> Well, I'm thinking like in book publishing, so there will be
> duplication.

So, like Debian Reference or Debian Handbook?

> My main concern is that I don't really know if maintaining the
> proposed structure using MoinMoin requires too much manual work. For
> example, I just tried to use the CopyPage [1] action in my local
> installation of MoinMoin
> and it didn't work (action not found :(). This feature could make it
> easier, for
> example, to copy a "stable" documentation to use it as the base for
> "dev" documentation.

I found that CopyPage is disabled by default "because of questionable
behaviour" according to the MoinMoin changelog. I suspect it has
something to do with ACLs. If that's the case then we can choose to
only enable it when we need to do a mass copy for a new release. It can
be enabled in wikiconfig like this:

    actions_excluded = list(DefaultConfig.actions_excluded)
    actions_excluded.remove('CopyPage')

It copies the page's history too and it can do recursive copies.

> Sometimes I'd like to be a dictator and make the documentation team
> use a DVCS [2], Sphinx [3] and RTD [4] for easier publishing :P Or
> use DVCS and Mallard [5] to have all the documentation integrated in
> the operating system itself (by the way, I gave Sam a documentation
> template [6] written in Mallard).

I was enthusiastic about that template because I thought we could also
easily import such documentation in the wiki. Today I read
HelpOnXmlPages [1] and played around with that a bit. It renders
DocBook if you add "#format docbook" as the first line. Not really a
problem, but in the end we're stuck with manually copying it in. Unless
we use xmlrpc, but that's not well documented and seems to have
security implications.

Sphinx and RTD are nice, but that means the documentation is separate
from the rest of the website, so users would have to look/search in 2
places.

I do like the idea of a gNewSense Handbook and I wouldn't mind it being
a separate resource if it were really good and maintained by several
people with a long-term commitment. Else we could still use the DVCS
approach for a gNewSense Introduction that we can package.

[1] http://www.gnewsense.org/HelpOnXmlPages