> On Aug 23, 2018, at 12:45 AM, Geert Janssens <[email protected]>
> wrote:
>
> Op dinsdag 21 augustus 2018 21:24:25 CEST schreef John Ralls:
>>> On Aug 21, 2018, at 11:50 AM, Geert Janssens <[email protected]>
>>> wrote: - it should allow multiple output formats. A few the come to mind:
>>> html, pdf, epub, mobi, windows compressed help, xml for yelp,...
>>
>> We don't need a single tool to do that; in fact we don't use a single tool
>> now. We create Windows compressed html (.chm) with HTML Help Workshop from
>> the xslt-created HTML and mobi with calibre from the xslt-created epub.
>>
> It appears while writing down the requirements, I was more considering our
> documentation system as a whole, not just a single tool. I agree this can
> consist of several tools glued together.
>
> I think what matters is the people actually writing the documentation should
> have to learn as few as possible to keep the barrier for contribution very
> low. More on that in reply to your other message.
>
>> That aside, I think we should reconsider windows compressed help.
>> Microsoft's own Windows 10 applications seem to open the browser to the
>> relevant documentation page on www.microsoft.com and the help browser is
>> still decorated with Windows 2000 frame and controls. It looks quite
>> jarring. We could more easily just open the documents in a GtkWebkitWebView
>> just like reports.
>
> I'm all for this. In fact I have proposed this in the past. That also rids us
> of one of the more annoying build dependencies on Windows (HtmlHelp).
>
> It would be nice if our html version of the docs would get some css love in
> that case though. Wading through plain rendered html is an equally 2000'ish
> experience.
I've been having another look at https://pandoc.org/. It consumes several
flavors of markdown and wiki markup as well as DocBook. It emits an impressive
range of output formats including DocBook, GNU texinfo (which is completely
unrelated to TeX), LaTeX, HTML, and Epub; the only deficiency from our view
would be that it doesn't directly emit PDF. It can do so indirectly via LaTeX
or we could generate DocBook and continue to use Apache XML-Format-Objects.
My original thought was that contributors could use it to convert the current
DocBook sources to Microsoft Word or LibreOffice format, edit in a familiar
word processor, and then use pandoc to convert back to DocBook. That didn't
work out very well in testing.
So a new thought: One of the core devs use pandoc to convert the DocBook source
to one of the markup/markdown variants, do the necessary manual fixups and
commit the result. If we want DocBook for some reason the build process would
use pandoc to generate it.
If we had GitHub-flavored markdown sources then
https://github.com/gnucash/gnucash-docs would show rendered documentation and
one could use the "preview" button to check basic layout; it would appear
pretty similar to how the document would look in a PDF or eBook rendering.
Regards,
John Ralls
_______________________________________________
gnucash-devel mailing list
[email protected]
https://lists.gnucash.org/mailman/listinfo/gnucash-devel
