Using AsciiDoc for Documentation

[John Ralls]

> 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