Using AsciiDoc for Documentation

David T. sunfish62 at yahoo.com
Wed Sep 2 22:06:30 EDT 2015


> On Sep 2, 2015, at 8:57 PM, John Ralls <jralls at ceridwen.us> wrote:
> 
> 
>> On Sep 2, 2015, at 10:36 AM, David T. <sunfish62 at yahoo.com> wrote:
>> 
>> 
>>> 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.
> 
> I don’t know that you’d need to run asciidoc itself. That would be part of the documentation build process. You’d just need to use a text editor to create or edit a file with asciidoc markup in it instead of Docbook markup. The question is “is asciidoc’s markup preferable to you over Docbook?”
> 
> Regards,
> John Ralls
> 

John,

I’ve looked at the documentation a little. It looks a lot like the wiki syntax. I personally don’t feel strongly about one format over another, except inasmuch as I have already spent a good bit of time learning the current documentation syntax.

Frankly, for me the problem has never been whether the documentation uses one obscure text-formatting format or another. I’ve been editing HTML code and any of a multitude of other text markup languages in text editors for decades. I just look at what’s already there, and copy it until I eventually get it learned. 

I will admit that as I age, I get less happy with the mental overhead of trying to imagine what things will ultimately look like—and I would hazard a guess that the language in the documents suffers because people have to spend mental cycles filtering out markup and imagining how things will look, rather than on what is actually being said. So, having a WYSIWIG editor would benefit the docs, I believe.

Ultimately, though, the problem for me with updating GnuCash documentation has always been about the workflow surrounding the actual editing. [I am reasonably sure that the developer list and those who must suffer with my mangling of the update/patching process would agree with my self-assessment.] The use of version control platforms for this aspect of the project may yield benefits to the developer base, but feels like an intense over-engineering—especially given the level of activity associated with the documentation (which is exceedingly low). I mean, if there actually were a group of even 4 people actively working on documentation in any given month, I would be surprised. Given this reality, is it REALLY necessary to use industrial version control on two (admittedly somewhat complex) documents? 

I am reminded of the MIDI music studio I had in the early 90s. At first, I enjoyed sitting down and improvising with sounds and notes with a single keyboard and amplifier. Then I decided to add a nifty cool sampler, a digital delay, a computer, and some other gadgets, and it got so complicated to get everything up and running that I would lose whatever musical inspiration induced me to turn it all on in the first place. I ended up getting an acoustic piano.

The GnuCash documentation update process is like this, with all the protocols around bugs and git, and xmllint-ing and xslt-ing before formatting an appropriate patch (and watch out that you don’t accidentally push a patch [or is that pick a peck?] that can’t be parsed). It’s a wonder that any of us writerly and not developer-ly types get through any of it.

David T.


More information about the gnucash-devel mailing list