Using AsciiDoc for Documentation (Geert Janssens)

Chris Good chris.good at ozemail.com.au
Thu Sep 3 18:40:38 EDT 2015 

FYI 

I remember the Documentation Update Instructions wiki suggests Serna Free could be used as a docbook editor although you have to remove some extraneous stuff.

I thought that it might be easier to modify Serna to not add the extraneous stuff, but AFAICT, Serna no longer seems to be available, although the source is in github.

Shall I remove reference to Serna from wiki?

Regards,

Chris Good

> On 3 Sep 2015, at 2:00 am, gnucash-devel-request at gnucash.org wrote:
> 
> Send gnucash-devel mailing list submissions to
>    gnucash-devel at gnucash.org
> 
> To subscribe or unsubscribe via the World Wide Web, visit
>    https://lists.gnucash.org/mailman/listinfo/gnucash-devel
> or, via email, send a message with subject or body 'help' to
>    gnucash-devel-request at gnucash.org
> 
> You can reach the person managing the list at
>    gnucash-devel-owner at gnucash.org
> 
> When replying, please edit your Subject line so it is more specific
> than "Re: Contents of gnucash-devel digest..."
> 
> 
> Today's Topics:
> 
>   1. Re: Using AsciiDoc for Documentation (Geert Janssens)
>   2. Re: Using AsciiDoc for Documentation (Geert Janssens)
>   3. Re: Doxygen Warnings (Derek Atkins)
>   4. Re: Using LaTex for Documentation (Derek Atkins)
>   5. Re: Using LaTex for Documentation (Geert Janssens)
>   6. Re: Using LaTex for Documentation (Ted Creedon)
>   7. Re: Using AsciiDoc for Documentation (David T.)
> 
> 
> ----------------------------------------------------------------------
> 
> Message: 1
> Date: Wed, 02 Sep 2015 16:20 +0200
> From: Geert Janssens <geert.gnucash at kobaltwit.be>
> To: gnucash-devel at gnucash.org
> Subject: Re: Using AsciiDoc for Documentation
> Message-ID: <1550541.652N917CiJ at legolas.kobaltwit.lan>
> Content-Type: text/plain; charset="us-ascii"
> 
>> On Wednesday 02 September 2015 10:55:34 Mike Evans wrote:
>> On Tue, 1 Sep 2015 13:44:39 -0500
>> 
>> Rob Gowin <robg at gowin.net> wrote:
>>>>> On Sep 1, 2015, at 4:56 AM, Mike Evans <mikee at saxicola.co.uk> wrote:
>>>>> [snip]
>>>> 
>>>> Hi Rob
>>>> 
>>>> Looks good to me. Still a few minor bugs with the Asciidoc.
>>>> 
>>>> Some of the Figure titles are missing
>>>> Second level bullet indents missing
>>>> 
>>>> But these are minor and some tweaking of the XSL should fix that. 
>>>> Speaking of which, I notice the XSL isn't in github can you make
>>>> that available somewhere so others can chip in with help? I'd
>>>> also like to generate the Asciidoc locally so I can ensure both
>>>> formats are from the same source for comparison purposes.
>>>> 
>>>> Now you (we) have to convince others to use Asciidoc!
>>>> 
>>>> I use Geany for my coding/writing and there is a Markdown plugin
>>>> for preview, no Asciidoc at the moment though.  I'm looking at
>>>> the PEG code to see how difficult it would be to produce an
>>>> Asciidoc previewer plugin.  It may be beyond my learning
>>>> tolerance though.
>>>> 
>>>> Mike E
>>> 
>>> Hi Mike,
>>> 
>>> Thanks for taking a look. I have put the XSL file and a python
>>> script to run the conversion process in a repository at
>>> https://github.com/codesmythe/asciidoc-conversion. See the README
>>> there for details.
>>> 
>>> As for editors, I just use a command line converter and then
>>> reload the generated HTML into a browser. I need to try some of the
>>> live preview editors mentioned in the link you sent out yesterday.
>>> 
>>> I'll look at the issues you mentioned in the next couple of days.
>>> 
>>> Thanks,
>>> 
>>> Rob
>> 
>> Hi Rob
>> 
>> Bearing in mind this would only ever need to be run once for each
>> document set and that Asciidoc may not be adopted anyway it's
>> probably not worth spending a lot of effort on those final issues for
>> the moment.  They can likely be easily(ish) fixed manually after
>> conversion.
>> 
>> Mike E
> 
> Mike, Rob,
> 
> Thanks for enthusiastically evaluating asciidoc. Until now I haven't had the chance to look at it 
> and just did so superficially. 
> 
> In general I'm open for all alternatives if they represent a step forward in our documentation 
> needs.
> 
> I remember Christian Stimming rejecting asciidoc in the original discussion because it still 
> requires the user to learn a markup structure, which he considered too much of a barrier for 
> new contributors.
> 
> Having said that, it seems asciidoc has more or less the same advantages and disadvantages 
> as markup. It looks to be slightly more expressive than markup.
> 
> As with markup the primary drawback I currently see is the lack of a wysiwyg capable editor 
> that's present on all platforms we support.
> 
> I agree with John we should ask the opinion of those users that are currently expressing interest 
> in contributing to the documentation.
> 
> Regards,
> 
> Geert
> 
> 
> ------------------------------
> 
> Message: 2
> Date: Wed, 02 Sep 2015 16:24:24 +0200
> From: Geert Janssens <geert.gnucash at kobaltwit.be>
> To: gnucash-devel at gnucash.org
> Cc: Mechtilde Stehmann <ooo at mechtilde.de>, Chris Good
>    <chris.good at ozemail.com.au>
> Subject: Re: Using AsciiDoc for Documentation
> Message-ID: <4304626.RrUXSRCXYZ at legolas.kobaltwit.lan>
> Content-Type: text/plain; charset="utf-8"
> 
> On Wednesday 02 September 2015 06:45:38 John Ralls wrote:
>>> On Sep 2, 2015, at 2:55 AM, Mike Evans <mikee at saxicola.co.uk> wrote:
>>> 
>>> On Tue, 1 Sep 2015 13:44:39 -0500
>>> 
>>> Rob Gowin <robg at gowin.net> wrote:
>>>>>> On Sep 1, 2015, at 4:56 AM, Mike Evans <mikee at saxicola.co.uk> wrote:
>>>>>> [snip]
>>>>> 
>>>>> Hi Rob
>>>>> 
>>>>> Looks good to me. Still a few minor bugs with the Asciidoc.
>>>>> 
>>>>> Some of the Figure titles are missing
>>>>> Second level bullet indents missing
>>>>> 
>>>>> But these are minor and some tweaking of the XSL should fix that. 
>>>>> Speaking of which, I notice the XSL isn't in github can you make
>>>>> that available somewhere so others can chip in with help? I'd
>>>>> also like to generate the Asciidoc locally so I can ensure both
>>>>> formats are from the same source for comparison purposes.
>>>>> 
>>>>> Now you (we) have to convince others to use Asciidoc!
>>>>> 
>>>>> I use Geany for my coding/writing and there is a Markdown plugin
>>>>> for preview, no Asciidoc at the moment though.  I'm looking at
>>>>> the PEG code to see how difficult it would be to produce an
>>>>> Asciidoc previewer plugin.  It may be beyond my learning
>>>>> tolerance though.
>>>>> 
>>>>> Mike E
>>>> 
>>>> Hi Mike,
>>>> 
>>>> Thanks for taking a look. I have put the XSL file and a python
>>>> script to run the conversion process in a repository at
>>>> https://github.com/codesmythe/asciidoc-conversion. See the README
>>>> there for details.
>>>> 
>>>> As for editors, I just use a command line converter and then
>>>> reload the generated HTML into a browser. I need to try some of the
>>>> live preview editors mentioned in the link you sent out yesterday.
>>>> 
>>>> I'll look at the issues you mentioned in the next couple of days.
>>>> 
>>>> Thanks,
>>>> 
>>>> Rob
>>> 
>>> Hi Rob
>>> 
>>> Bearing in mind this would only ever need to be run once for each
>>> document set and that Asciidoc may not be adopted anyway it's
>>> probably not worth spending a lot of effort on those final issues
>>> for the moment.  They can likely be easily(ish) fixed manually
>>> after conversion.
>> Well, let?s poll the person most likely to make use of the switch:
>> 
>> David Carlson, please have a look at
>> http://asciidoc.org/userguide.html, starting at section 8, and tell
>> us if you?d be able to easily edit documents in that format.
> David T. is currently actively working on the English documentation. And I also saw patches 
> by Chris Good recently. Additionally Mechtilde Stehmann is working on the German 
> translation as well.
> 
> All good candidates to let us know how they perceive asciidoc/markup versus the current 
> docbook format. I'm not sure they are all subscribed to the devel list so exceptionally I have 
> addressed them directly in addition to the list.
> 
> Regards,
> 
> Geert
> 
> 
> ------------------------------
> 
> Message: 3
> Date: Wed, 02 Sep 2015 10:51:59 -0400
> From: Derek Atkins <warlord at MIT.EDU>
> To: John Ralls <jralls at ceridwen.us>
> Cc: gnucash-devel at gnucash.org, Matt Graham
>    <matt_graham2001 at hotmail.com>
> Subject: Re: Doxygen Warnings
> Message-ID: <sjmpp20ho1c.fsf at securerf.ihtfp.org>
> Content-Type: text/plain
> 
> John Ralls <jralls at ceridwen.us> writes:
> 
>>> On Sep 1, 2015, at 2:53 PM, Matt Graham <matt_graham2001 at hotmail.com> wrote:
>>> 
>>> Thanks John,
>>> 
>>> I'm running doxygen directly on the src directory of the code.
>>> 
>>> Windows 8.1 at the moment. I'm travelling for work at the moment,
>>> when I get home over the weekend I'll try it on my gentoo box too
>> 
>> Matt,
>> 
>> That probably explains your trouble. You can either use `make docs` or
>> copy all of the configuration from it into your Doxygen setup. Make
>> will be easier if you have a Mingw build setup, but getting that might
>> not be worth it just to run Doxygen.
> 
> For the record the server calls doxygen directly (after using the
> makefile to generate doxygen.cfg from the input file).  The script
> basically does:
> 
> git fetch
> git reset --hard origin/master
> # Compute the version from the configure script
> VERSION=`grep AC_INIT configure.ac | awk '{print $2}' | sed -e 's/\[//' -e 's/\]
> ,//'`
> touch Makefile
> make -f Makefile.am doxygen.cfg top_srcdir=$top_srcdir VERSION="$VERSION"
> doxygen doxygen.cfg
> 
> So... it *should* be safe to run doxygen directly.
> 
> I'll note that the nightly script does redirect all output to /dev/null,
> so it wont report any warnings!  It will only report an outright
> failure.  I.e., it's quite possible that there are hundreds of warnings
> in there.
> 
>> Regards,
>> John Ralls
> 
> -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
> 
> 
> ------------------------------
> 
> Message: 4
> Date: Wed, 02 Sep 2015 10:53:34 -0400
> From: Derek Atkins <warlord at MIT.EDU>
> To: Ted Creedon <tcreedon at easystreet.net>
> Cc: "gnucash-devel at gnucash.org" <gnucash-devel at gnucash.org>
> Subject: Re: Using LaTex for Documentation
> Message-ID: <sjmlhcohnyp.fsf at securerf.ihtfp.org>
> Content-Type: text/plain
> 
> Ted Creedon <tcreedon at easystreet.net> writes:
> 
>> I find I quite easy to use and the typesetting is superb. Especially
>> if equations are needed.
> 
> I know of no equations required for the GnuCash documentation.
> 
>> Xml is a hack
> 
> How do you go from (La)TeX to HTML or ePub?  I only know how to get to
> DVI, PS (via DVI), and PDF (via DVI or directly using pdflatex).
> 
>> Ted
> 
> -derek
> 
>> ________________________________________
>> From: John Ralls <jralls at ceridwen.us>
>> Sent: Tuesday, September 1, 2015 7:07:13 AM
>> To: Ted Creedon
>> Cc: gnucash-devel at gnucash.org
>> Subject: Re: Using LaTex for Documentation
>> 
>>> On Sep 1, 2015, at 3:38 AM, Ted Creedon <tcreedon at easystreet.net> wrote:
>>> 
>>> whats wrong with Latex?
>>> 
>>> It works fine and produces a permuted index too
>> 
>> Besides being even geekier and harder to convert to ePub and HTML than
>> Docbook? Probably nothing much.
>> 
>> Regards,
>> John Ralls
>> 
>> 
>> _______________________________________________
>> gnucash-devel mailing list
>> gnucash-devel at gnucash.org
>> https://lists.gnucash.org/mailman/listinfo/gnucash-devel
> 
> -- 
>       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
> 
> 
> ------------------------------
> 
> Message: 5
> Date: Wed, 02 Sep 2015 17:39:34 +0200
> From: Geert Janssens <geert.gnucash at kobaltwit.be>
> To: gnucash-devel at gnucash.org
> Subject: Re: Using LaTex for Documentation
> Message-ID: <8381643.6vzACJVj8m at legolas.kobaltwit.lan>
> Content-Type: text/plain; charset="us-ascii"
> 
> On Tuesday 01 September 2015 07:07:13 John Ralls wrote:
>>> On Sep 1, 2015, at 3:38 AM, Ted Creedon <tcreedon at easystreet.net>
>>> wrote:
>>> 
>>> whats wrong with Latex?
>>> 
>>> It works fine and produces a permuted index too
>> 
>> Besides being even geekier and harder to convert to ePub and HTML than
>> Docbook? Probably nothing much.
> For me the geeky nature is not relevant.
> 
> I care about an easy way to write documentation ideally wysiwym (as opposed to wysiwyg) and 
> easy to merge patches.
> 
> For latex documents I found LyX [1], which seems to be a free wysiwym editor available on all 
> major platforms. I haven't found ways yet to convert from docbook to latex, so getting started 
> may be a bigger hurdle here. There is dblatex but my first run failed to do the conversion. It 
> may work after some more tweaking.
> 
> The conversion to epub should not be too hard. Generating pdf from latex is the natural flow of 
> things and there are lots of pdf to epub convertors around. So I presume one of them will be 
> able to do the job.
> 
> Html is less clear. There's a document (last modified in 2007) which documents a process to 
> convert from latex to docbook [3] which would extend our current workflow. I is unfortunately 
> based on lyx 1.2.0, which is ancient and in addition it brings in a lot of dependencies.
> 
> Then this page lists several latex to html converters [4]. I haven't gotten around to test them 
> so I can't say much for the quality of the generated html.
> 
> Geert
> 
> [1] https://en.wikipedia.org/wiki/LyX
>    http://www.lyx.org/
> [2] http://dblatex.sourceforge.net/
> [3] http://www.karakas-online.de/mySGML/
> [4] http://www.tex.ac.uk/FAQ-LaTeX2HTML.html
> 
> 
> ------------------------------
> 
> Message: 6
> Date: Wed, 2 Sep 2015 16:01:30 +0000
> From: Ted Creedon <tcreedon at easystreet.net>
> To: "gnucash-devel at gnucash.org" <gnucash-devel at gnucash.org>
> Subject: Re: Using LaTex for Documentation
> Message-ID:
>    <SN1PR14MB025426138AB0D5FD76A7FBC6A4690 at SN1PR14MB0254.namprd14.prod.outlook.com>
>    
> Content-Type: text/plain; charset="us-ascii"
> 
> I hack using word and do a word to latex conversion
> 
> If you want I can setup a tooling stream, I presume that the permuted index needs to be created after conversion
> 
> Send me a file to convert
> 
> Tedc
> ________________________________
> From: Geert Janssens <geert.gnucash at kobaltwit.be>
> Sent: Wednesday, September 2, 2015 8:39:34 AM
> To: gnucash-devel at gnucash.org
> Cc: John Ralls; Ted Creedon
> Subject: Re: Using LaTex for Documentation
> 
> 
> On Tuesday 01 September 2015 07:07:13 John Ralls wrote:
> 
>>> On Sep 1, 2015, at 3:38 AM, Ted Creedon <tcreedon at easystreet.net>
> 
>>> wrote:
> 
> 
>>> whats wrong with Latex?
> 
> 
>>> It works fine and produces a permuted index too
> 
> 
>> Besides being even geekier and harder to convert to ePub and HTML than
> 
>> Docbook? Probably nothing much.
> 
> 
> For me the geeky nature is not relevant.
> 
> 
> 
> I care about an easy way to write documentation ideally wysiwym (as opposed to wysiwyg) and easy to merge patches.
> 
> 
> 
> For latex documents I found LyX [1], which seems to be a free wysiwym editor available on all major platforms. I haven't found ways yet to convert from docbook to latex, so getting started may be a bigger hurdle here. There is dblatex but my first run failed to do the conversion. It may work after some more tweaking.
> 
> 
> 
> The conversion to epub should not be too hard. Generating pdf from latex is the natural flow of things and there are lots of pdf to epub convertors around. So I presume one of them will be able to do the job.
> 
> 
> 
> Html is less clear. There's a document (last modified in 2007) which documents a process to convert from latex to docbook [3] which would extend our current workflow. I is unfortunately based on lyx 1.2.0, which is ancient and in addition it brings in a lot of dependencies.
> 
> 
> 
> Then this page lists several latex to html converters [4]. I haven't gotten around to test them so I can't say much for the quality of the generated html.
> 
> 
> 
> Geert
> 
> 
> 
> [1] https://en.wikipedia.org/wiki/LyX
> 
> http://www.lyx.org/
> 
> [2] http://dblatex.sourceforge.net/
> 
> [3] http://www.karakas-online.de/mySGML/
> 
> [4] http://www.tex.ac.uk/FAQ-LaTeX2HTML.html
> 
> 
> ------------------------------
> 
> Message: 7
> Date: Wed, 2 Sep 2015 13:36:59 -0400
> From: "David T." <sunfish62 at yahoo.com>
> To: John Ralls <jralls at ceridwen.us>
> Cc: GnuCash development list <gnucash-devel at gnucash.org>
> Subject: Re: Using AsciiDoc for Documentation
> Message-ID: <DBF4FCE3-5B55-46E2-99E1-F9525C9603F0 at yahoo.com>
> Content-Type: text/plain; charset=utf-8
> 
> 
>> On Sep 2, 2015, at 9:45 AM, John Ralls <jralls at ceridwen.us> wrote:
>> 
>> 
>>> On Sep 2, 2015, at 2:55 AM, Mike Evans <mikee at saxicola.co.uk> wrote:
>>> 
>>> On Tue, 1 Sep 2015 13:44:39 -0500
>>> Rob Gowin <robg at gowin.net> wrote:
>>> 
>>>> 
>>>>>> On Sep 1, 2015, at 4:56 AM, Mike Evans <mikee at saxicola.co.uk> wrote:
>>>>>> [snip]
>>>>> 
>>>>> Hi Rob
>>>>> 
>>>>> Looks good to me. Still a few minor bugs with the Asciidoc.  
>>>>> 
>>>>> Some of the Figure titles are missing
>>>>> Second level bullet indents missing
>>>>> 
>>>>> But these are minor and some tweaking of the XSL should fix that.  Speaking of which, I notice the XSL isn't in github can you make that available somewhere so others can chip in with help? I'd also like to generate the Asciidoc locally so I can ensure both formats are from the same source for comparison purposes.
>>>>> 
>>>>> Now you (we) have to convince others to use Asciidoc!
>>>>> 
>>>>> I use Geany for my coding/writing and there is a Markdown plugin for preview, no Asciidoc at the moment though.  I'm looking at the PEG code to see how difficult it would be to produce an Asciidoc previewer plugin.  It may be beyond my learning tolerance though.
>>>>> 
>>>>> Mike E
>>>>> 
>>>>> 
>>>>> 
>>>>> -- 
>>>>> PGP key:
>>>>> http://pgp.mit.edu:11371/pks/lookup?op=get&search=0x00CDB13500D7AB53  
>>>> 
>>>> 
>>>> Hi Mike,
>>>> 
>>>> Thanks for taking a look. I have put the XSL file and a python
>>>> script to run the conversion process in a repository at 
>>>> https://github.com/codesmythe/asciidoc-conversion. See the README
>>>> there for details.
>>>> 
>>>> As for editors, I just use a command line converter and then
>>>> reload the generated HTML into a browser. I need to try some of the
>>>> live preview editors mentioned in the link you sent out yesterday.
>>>> 
>>>> I'll look at the issues you mentioned in the next couple of days.
>>>> 
>>>> Thanks,
>>>> 
>>>> Rob
>>> 
>>> Hi Rob
>>> 
>>> Bearing in mind this would only ever need to be run once for each document set and that Asciidoc may not be adopted anyway it's probably not worth spending a lot of effort on those final issues for the moment.  They can likely be easily(ish) fixed manually after conversion.  
>> 
>> Well, let?s poll the person most likely to make use of the switch:
>> 
>> David Carlson, please have a look at http://asciidoc.org/userguide.html, starting at section 8, and tell us if you?d be able to easily edit documents in that format.
>> 
>> Regards,
>> John Ralls
>> 
>> 
>> _______________________________________________
>> gnucash-devel mailing list
>> gnucash-devel at gnucash.org
>> https://lists.gnucash.org/mailman/listinfo/gnucash-devel
> 
> Although I am not named above, I will note that a quick examination of the asciidoc pages fails to turn up a readily-available OS X (as in ?Here is the dmg. Download it and install it like other Mac apps.?) version of the program. I?ve been down the Fink/Homebrew/MacPorts rabbit hole before (most notably with GnuCash itself), and I can honestly say that I will not be using asciidoc for creating or managing documentation. My life is too short for that.
> 
> David (T.)
> 
> 
> ------------------------------
> 
> Subject: Digest Footer
> 
> _______________________________________________
> gnucash-devel mailing list
> gnucash-devel at gnucash.org
> https://lists.gnucash.org/mailman/listinfo/gnucash-devel
> 
> 
> ------------------------------
> 
> End of gnucash-devel Digest, Vol 150, Issue 3
> *********************************************

More information about the gnucash-devel mailing list