Some Assistance Please

Derek Atkins warlord at MIT.EDU
Thu May 25 10:45:34 EDT 2017


Adrien,

Adrien Monteleone <adrien.monteleone at gmail.com> writes:

> Geert,
>
> If the opposite were possible, would that meet the needs?
>
> If using the wiki as the collaboration platform opened up
> documentation editing to non-developer types but still gave you the
> desired formats, is that what you are looking for or are there other
> needs?

This was the road we've looked at and attempted in the past -- moving
the documentation development onto the Wiki and then using that to
produce the various formats required for yelp, windows help, etc.  The
results were.... less than stunning.

This is why we're reluctant to try again without an existence proof that
the tools have significantly improved and will produce documentation
that is at least as good as the current process.

> Looking over mediawiki.org, there are methods using our own render
> server (or a public one if so desired) and extension plugins to export
> a variety of formats including XHTML, PDF, ePUB, ZIM, ODF, and yes,
> DocBook XML. There’s also the option of using PediaPress for people to
> order a physical bound copy if they so desire.

If we could translate into Docbook then we could leverage the existing
tools to generate the outputs we require.  However, how well does the
tool translate from wiki -> Docbook?

> The only one presently offered I don’t see included as an extension is
> MOBI though there are many tools to take any of those other formats to
> MOBI if really needed. I would think it not too difficult to script
> the conversion of a resulting ePUB into MOBI. Clicking the MOBI
> download link could take a trip through ePUB and then the ePub2Mobi
> conversion to serve the desired file. Is there still a significant
> case for .mobi files due to .mobi only readers? Is there a current
> comparison of download stats from gnucash.org?

I dont know if there are download stats available from code and/or www.

> An additional advantage of using the wiki as the working and
> publishing platform is that formats are generated on-demand by the
> render server. Thus any time someone downloads a copy of the
> documentation it will always be the most up to date, rather than a
> milestone-released static version. If that is not desired I suppose
> some method of drafts vs. published approved pages would suffice, but
> that will more than likely be handled by control of editing
> credentials.

That's not desired; we want the documentation to match the release.
Someone with 2.4 is better served with the 2.4 documentation.  Someone
with 2.6 with the 2.6 documentation.  Someone running 2.4 who looks at
the 2.6 docs might get confused.

> The render server can also be configured to ‘publish’ specific
> collections of articles so that the wiki could contain the entirety of
> the help, tutorial and concepts guide, developer documentation, et
> cetera, and then particular links will give you a single file of any
> one of those. So if someone wanted a printed copy of the help and a
> pdf of the tutorial and concepts guide, they could get each separately
> all from the wiki and all with the most current approved edits.

The developer documentation is generated by doxygen from the source
code.  Moving that into the wiki would be, IMHO, the wrong thing to do.
The dev docs should live with the code.

> Just a thought.
>
> -Adrien

-derek
-- 
       Derek Atkins, SB '93 MIT EE, SM '95 MIT Media Laboratory
       Member, MIT Student Information Processing Board  (SIPB)
       URL: http://web.mit.edu/warlord/    PP-ASEL-IA     N1NWH
       warlord at MIT.EDU                        PGP key available


More information about the gnucash-devel mailing list