Re: Using AsciiDoc for Documentation

[John Ralls]

> On Sep 4, 2015, at 4:25 AM, Mike Evans  wrote:
> 
> On Thu, 03 Sep 2015 12:29:15 +0200
> Geert Janssens  wrote:
> 
>> On Thursday 03 September 2015 01:28:59 Buddha Buck wrote:
>>> On Wed, Sep 2, 2015 at 10:20 AM Geert Janssens
>>> 
>>> wrote:
 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.
>>> 
>>> By "markup" here do you mean "Markdown"?
>>> 
>> Indeed. I don't know why I started using it markup all of a sudden...
>> 
> 
> Small note regarding Markdown, It doesn't support tables.  Plus a few other 
> things that Asciidoc does.  There is Multimarkdown though, which supports 
> more structures.

More to the point since we were talking about using Markdown inside of Doxygen 
is that Doxygen’s Markdown is extended to create tables: 
https://www.stack.nl/~dimitri/doxygen/manual/markdown.html#md_tables

Regards,
John Ralls


___
gnucash-devel mailing list
gnucash-devel@gnucash.org
https://lists.gnucash.org/mailman/listinfo/gnucash-devel

Re: Using AsciiDoc for Documentation

[Mike Evans]

On Wed, 2 Sep 2015 22:06:30 -0400
"David T."  wrote:

>  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? 

Regarding this...

Running 
git log  c180e4d1548857.. --format="%aN" --reverse | sort | uniq
which gives all the authors this year, in gnucash-docs returns the following 
list

Alex Aycinena
Benjamin Melançon
Carl Reinke
Chris Good
Cristian Marchi
DanielDodson
David
David T
Derek Atkins
Dmitry Pavlov
Frank H. Ellenberger
Geert Janssens
John Ralls
Mark Simpson
Martin Mainka
Mechtilde
Mechtilde Stehmann
Mike Evans
Raphael Kubo da Costa

which is 17 (after removing duplicates).

Mike E



-- 
PGP key:
http://pgp.mit.edu:11371/pks/lookup?op=get=0x00CDB13500D7AB53  

___
gnucash-devel mailing list
gnucash-devel@gnucash.org
https://lists.gnucash.org/mailman/listinfo/gnucash-devel

Re: Using AsciiDoc for Documentation

[Geert Janssens]

On Thursday 03 September 2015 01:28:59 Buddha Buck wrote:
> On Wed, Sep 2, 2015 at 10:20 AM Geert Janssens
> 
> wrote:
> > 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.
> 
> By "markup" here do you mean "Markdown"?
> 
Indeed. I don't know why I started using it markup all of a sudden...

> If so, there are a number of wysiwyg-like editors available, presuming
> that two panes, one with the plain markdown, the other a real-time
> rendered preview, is sufficient.
> 
As I briefly mentioned in another part of this thread, I think it helps but I'm 
not sure it will be 
sufficient for new contributors to learn.

I had seen those editors with previews (and mentioned them in the preceding 
thread (Replacing 
Docbook).

> Atom (http://www.atom.io) is a very capable "hackable" editor which
> supports Markdown with preview pane out of the box. It's open source
> and supports Linux, Mac, and Windows
> 
> Remarkable (https://remarkableapp.github.io/
> ) is a Windows/Linux open
> source Markdown editor with live preview, and also will export HTML
> and PDF out of the box. It does not claim MacOS support.
> 
> CuteMarkEd (https://cloose.github.io/CuteMarkEd/) uses Qt as it's
> platform, and thus supports Linux, Windows, and possibly Mac if
> compiled from source. It has similar features as the others.
> 
>  I also haven't been paying close attention so I don't know if pandoc
> ( http://pandoc.org/index.html) has been evaluated for document
> conversion. It seems to support converting every input file format
> under discussion to every output file format under discussion. Did I
> miss the discussion?

I didn't know about pandoc. A very interesting tool at first sight.

I quickly used it to run some tests.

Conversion of our docbook to latex ran successfully but LyX can't open the 
document.

I also ran a conversion to opendocument format (.odt). It does better than the 
outdated 
docbook2odt in that it resizes the images. Links are still missing though and 
are replaced with 
question marks.

Next I tried a conversion to asciidoc. Again the links were acting up. I wonder 
if we're 
improperly using them in our original docbook format already. Other than that 
the document 
looked fine on first glance.


Perhaps we're just trying to find a solution that's too rigid. If a tool such 
as pandoc really works 
well we may be able to choose one base document format and accept patches from 
different 
formats that just need one conversion step to apply to the base format. Oh 
well, that's just 
dreaming out loud for now...

I'll probably continue to play with pandoc to study it's potential. Thanks for 
bringing it up.

Geert.
___
gnucash-devel mailing list
gnucash-devel@gnucash.org
https://lists.gnucash.org/mailman/listinfo/gnucash-devel

Re: Using AsciiDoc for Documentation

[Geert Janssens]

On Wednesday 02 September 2015 22:06:30 David T. wrote:
> 
> 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.
> 
I almost agree.

The use of the term "look like" is key. As you no doubt know the focus of xml 
and its variants 
such as html focus on structure and defer the visual representation to css. So 
what the 
document "looks like" should not be the concern. Instead how it is structured 
should be. This is a 
subtle but important difference.

I recently learned the term "WYSIWYM", which stands for "What You See Is What 
You Mean". And 
I would much rather find a good WYSIWYM editor for our documentation than a 
WYSIWYG one.

The problem with pure WYSIWYG editors is that less experienced people typically 
tend to focus 
more on the visual appearance than on the structure of the document. A simple 
example: you 
could mimic a heading by setting the font size and bold-face manually, but 
that's structurally 
not a heading and hence won't show up in automatically generated table of 
contents.

WYSIWYM is close to WYSIWYG but will put the focus on document structure. The 
structure is 
visually represented similar to WYSIWYG to make it easier to follow as a normal 
human being 
what you are editing.

> 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 still think we do need some form of change management. For starters it's not 
just two 
documents. It's two documents translated in many languages, and maintained for 
two different 
versions of the program.

Without rigorous version control it becomes much harder to track the changes in 
the main 
document. Which parts have recently been modified that need translation still ? 
Which recent 
changes should also be applied to the documentation matching the development 
version 
gnucash ?

My experience shows this quickly gets a mess without some decent version 
management. The 
amount of people working on this is less relevant. Even a single user project 
with so many 
interdependent documents is easier to track via some form of change management.

I understand this feels like overhead. I understand git is confusing to people 
first introduced to 
it. I know from experience *any* change management system has this effect, 
because it forces 
people to think in terms of, well, "manageable changes". I'm sorry I don't know 
how to lower 
this barrier to entry.


> 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.

Let me point out that the xmllint-ing and 

Re: Using AsciiDoc for Documentation (Geert Janssens)

[John Ralls]

> On Sep 3, 2015, at 3:40 PM, Chris Good  wrote:
> 
> 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?

Huh. I wonder if it was one of those “mirrored without permission” packages 
that they removed last spring.

Anyway, yeah, you might as well remove it. I don’t think anyone was interested 
in using it, and since one now must build it from source it’s too hard for 
non-programmers to get anyway.

Regards,
John Ralls


___
gnucash-devel mailing list
gnucash-devel@gnucash.org
https://lists.gnucash.org/mailman/listinfo/gnucash-devel

Re: Using AsciiDoc for Documentation (Geert Janssens)

[Chris Good]

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-requ...@gnucash.org wrote:
> 
> Send gnucash-devel mailing list submissions to
>gnucash-devel@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-requ...@gnucash.org
> 
> You can reach the person managing the list at
>gnucash-devel-ow...@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.gnuc...@kobaltwit.be>
> To: gnucash-devel@gnucash.org
> Subject: Re: Using AsciiDoc for Documentation
> Message-ID: <1550541.652n917...@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 <r...@gowin.net> wrote:
>>>>> On Sep 1, 2015, at 4:56 AM, Mike Evans <mi...@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 
>

Re: Using AsciiDoc for Documentation

[Mechtilde]

-BEGIN PGP SIGNED MESSAGE-
Hash: SHA512

Hello,

for me there is no difference to use docbook or asciidoc. In general I
use the predefined structure.

Kind regards

Mechtilde

Am 02.09.2015 um 16:24 schrieb Geert Janssens:
> On Wednesday 02 September 2015 06:45:38 John Ralls wrote:
>>> On Sep 2, 2015, at 2:55 AM, Mike Evans 
>>> wrote:
>>> 
>>> On Tue, 1 Sep 2015 13:44:39 -0500
>>> 
>>> Rob Gowin  wrote:
> On Sep 1, 2015, at 4:56 AM, Mike Evans
>  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
> 

- -- 
Mechtilde Stehmann
## Apache OpenOffice.org
## Freie Office Suite für Linux, MacOSX, Windows
## Loook, calender-exchange-provider, libreoffice-canzeley-client
## PGP encryption welcome
## Key-ID 0x141AAD7F
-BEGIN PGP SIGNATURE-
Version: GnuPG v2

iQIcBAEBCgAGBQJV6GjRAAoJEPKHe7oUGq1/6uMP/RKtnxLftmixMKEcouPPX4Uy
Wcn9rtMiOo6pgNwwmhvDnHtB1VwMJk0rJUXmFe+WXb7nqIHfA5EW60t1H1hZUwVD
aiRtbGurqrI0Dr40bmI/RXbXWkx+nDieP+YYyAE11LIzPUn+yF8k4Msidj9cqVjK
cc5Cf6VXmxoxbEy8DTW8jYsGkrPJqNuIToT6XyZgFd/93x+UYZpgQASwvRyhYIFX
1bb4/7y3u1jfDRvBLOIWMC+80D9tXiIxOkMiZfpDpLMtu9qSSVDVWUCchxa7px1/
1OG9wyE/7VfbIitJ8iIlZLQ0fxx+1wPXNnArbxVDiS+aPsVmoMDKwocCBKbGdC3o
6YWCp2KtM+/1hFErtoyiEMqz/oH1uKt0Eu97V/XFUTw9YZF4D5KKFhpfN5zMcytE
JztnXbyG3rD5m0TIwwoNzPCzOx+jiTyeoEpspAOlKVPk6Dz0pkSDxyyInAViS966
1sMzDhmxKyp48eyxUVgM5H/K3WtM6aQR43OojFge0/54/vriLGiDEfXI+JXXvKaz
xAIA2wvVKfMuxW6mXAsqwILEV/LLnnzeRUJRchSA+6Q4yZoMmq+qlmI3rhBgYMYN
68haWsCOQNd/bxzcH7bI1ZdvErqaGh1IOOHCBmpvphrVgRqhcGSiGZX3yp2VUSVP
kkI3PcqgqnxJgSpMBNfq
=Zvu1
-END PGP SIGNATURE-
___
gnucash-devel mailing list
gnucash-devel@gnucash.org
https://lists.gnucash.org/mailman/listinfo/gnucash-devel

Re: Using AsciiDoc for Documentation

[Chris Good]

Hi devs,

I've been following this discussion and had a look at the asciidoc website.
I could use asciidoc but unless there is a wysiwyg editor available on Linux or 
Windows (I don't have a Mac), I cannot see any advantage. I currently use jEdit 
with xml plugin and another plugin I cannot currently remember the name of, 
which draws nice vertical lines to show matching start/end tags.

Occasionally I get stuck for a while with docbook syntax, but I'm getting ok at 
it now.
I agree that it must be difficult, if not impossible, for non programmers to 
use.
However, if they write text and put it in a bug, I'm happy to put it into the 
documentation as time permits.

Regards,

Chris Good


___
gnucash-devel mailing list
gnucash-devel@gnucash.org
https://lists.gnucash.org/mailman/listinfo/gnucash-devel

Re: Using AsciiDoc for Documentation

[David T.]

> On Sep 2, 2015, at 9:45 AM, John Ralls  wrote:
> 
> 
>> On Sep 2, 2015, at 2:55 AM, Mike Evans  wrote:
>> 
>> On Tue, 1 Sep 2015 13:44:39 -0500
>> Rob Gowin  wrote:
>> 
>>> 
 On Sep 1, 2015, at 4:56 AM, Mike Evans  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=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@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.)
___
gnucash-devel mailing list
gnucash-devel@gnucash.org
https://lists.gnucash.org/mailman/listinfo/gnucash-devel

Re: Using AsciiDoc for Documentation

[John Ralls]

> On Sep 2, 2015, at 10:36 AM, David T.  wrote:
> 
> 
>> On Sep 2, 2015, at 9:45 AM, John Ralls  wrote:
>> 
>> 
>>> On Sep 2, 2015, at 2:55 AM, Mike Evans  wrote:
>>> 
>>> On Tue, 1 Sep 2015 13:44:39 -0500
>>> Rob Gowin  wrote:
>>> 
 
> On Sep 1, 2015, at 4:56 AM, Mike Evans  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=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@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


___
gnucash-devel mailing list
gnucash-devel@gnucash.org
https://lists.gnucash.org/mailman/listinfo/gnucash-devel

Re: Using AsciiDoc for Documentation

[Buddha Buck]

On Wed, Sep 2, 2015 at 10:20 AM Geert Janssens 
wrote:

> 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.
>

By "markup" here do you mean "Markdown"?

If so, there are a number of wysiwyg-like editors available, presuming that
two panes, one with the plain markdown, the other a real-time rendered
preview, is sufficient.

Atom (http://www.atom.io) is a very capable "hackable" editor which
supports Markdown with preview pane out of the box. It's open source and
supports Linux, Mac, and Windows

Remarkable (https://remarkableapp.github.io/
) is a Windows/Linux open
source Markdown editor with live preview, and also will export HTML and PDF
out of the box. It does not claim MacOS support.

CuteMarkEd (https://cloose.github.io/CuteMarkEd/) uses Qt as it's platform,
and thus supports Linux, Windows, and possibly Mac if compiled from source.
It has similar features as the others.

 I also haven't been paying close attention so I don't know if pandoc (
http://pandoc.org/index.html) has been evaluated for document conversion.
It seems to support converting every input file format under discussion to
every output file format under discussion. Did I miss the discussion?
___
gnucash-devel mailing list
gnucash-devel@gnucash.org
https://lists.gnucash.org/mailman/listinfo/gnucash-devel

Re: Using AsciiDoc for Documentation

[David T.]

> On Sep 2, 2015, at 8:57 PM, John Ralls  wrote:
> 
> 
>> On Sep 2, 2015, at 10:36 AM, David T.  wrote:
>> 
>> 
>>> On Sep 2, 2015, at 9:45 AM, John Ralls  wrote:
>>> 
>>> 
 On Sep 2, 2015, at 2:55 AM, Mike Evans  wrote:
 
 On Tue, 1 Sep 2015 13:44:39 -0500
 Rob Gowin  wrote:
 
> 
>> On Sep 1, 2015, at 4:56 AM, Mike Evans  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=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@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 

Re: Using AsciiDoc for Documentation

[Mike Evans]

On Tue, 1 Sep 2015 13:44:39 -0500
Rob Gowin  wrote:

> 
> > On Sep 1, 2015, at 4:56 AM, Mike Evans  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=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.  

Mike E

-- 
PGP key:
http://pgp.mit.edu:11371/pks/lookup?op=get=0x00CDB13500D7AB53  
___
gnucash-devel mailing list
gnucash-devel@gnucash.org
https://lists.gnucash.org/mailman/listinfo/gnucash-devel

Re: Using AsciiDoc for Documentation

[John Ralls]

> On Sep 2, 2015, at 2:55 AM, Mike Evans  wrote:
> 
> On Tue, 1 Sep 2015 13:44:39 -0500
> Rob Gowin  wrote:
> 
>> 
>>> On Sep 1, 2015, at 4:56 AM, Mike Evans  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=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@gnucash.org
https://lists.gnucash.org/mailman/listinfo/gnucash-devel

Re: Using AsciiDoc for Documentation

[John Ralls]

> On Sep 2, 2015, at 2:55 AM, Mike Evans  wrote:
> 
> On Tue, 1 Sep 2015 13:44:39 -0500
> Rob Gowin  wrote:
> 
>> 
>>> On Sep 1, 2015, at 4:56 AM, Mike Evans  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=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.  

I guess the other test you guys need to do is to go back to Docbook, since that 
seems to be the gateway for generating everything we need besides HTML.

Regards,
John Ralls


___
gnucash-devel mailing list
gnucash-devel@gnucash.org
https://lists.gnucash.org/mailman/listinfo/gnucash-devel

Re: Using AsciiDoc for Documentation

[Geert Janssens]

On Wednesday 02 September 2015 10:55:34 Mike Evans wrote:
> On Tue, 1 Sep 2015 13:44:39 -0500
> 
> Rob Gowin  wrote:
> > > On Sep 1, 2015, at 4:56 AM, Mike Evans  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
___
gnucash-devel mailing list
gnucash-devel@gnucash.org
https://lists.gnucash.org/mailman/listinfo/gnucash-devel

Re: Using AsciiDoc for Documentation

[Geert Janssens]

On Wednesday 02 September 2015 06:45:38 John Ralls wrote:
> > On Sep 2, 2015, at 2:55 AM, Mike Evans  wrote:
> > 
> > On Tue, 1 Sep 2015 13:44:39 -0500
> > 
> > Rob Gowin  wrote:
> >>> On Sep 1, 2015, at 4:56 AM, Mike Evans  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
___
gnucash-devel mailing list
gnucash-devel@gnucash.org
https://lists.gnucash.org/mailman/listinfo/gnucash-devel

Re: Using AsciiDoc for Documentation

[Rob Gowin]

> On Sep 1, 2015, at 4:56 AM, Mike Evans  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=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




___
gnucash-devel mailing list
gnucash-devel@gnucash.org
https://lists.gnucash.org/mailman/listinfo/gnucash-devel

Re: Using AsciiDoc for Documentation

[Mike Evans]

On Sun, 30 Aug 2015 19:16:24 -0500
Rob Gowin <r...@gowin.net> wrote:

> [Hello List. Long time GnuCash user, -devel list lurker,
>  coming out of the shadows.]
> 
> > On Aug 29, 2015, at 5:43 AM, Mike Evans <mi...@saxicola.co.uk> wrote:
> > Another random thought then.
> >
> > I use asciidoc for pretty much all the docs I write, not much
> > admittedly but it's easy to learn and can produce many output formats.
> > I just used https://github.com/oreillymedia/docbook2asciidoc to
> > convert the guide to asciidoc using:
> >
> > $ java -jar /home/mikee/Projects/docbook2asciidoc/saxon9he.jar
> > -s gnucash-guide.xml -o gnucash-guide.asc
> > /home/mikee/Projects/docbook2asciidoc/d2a.xsl  chunk-output=true
> >
> > This produces an asccidoc file for each chapter plus the master page.
> >
> > [...]
> >
> > I'm not an expert on XML parsing using .xsl stylesheets but I suspect
> > this could be easily(?) remedied by editing the d2a.xsl to correctly
> > include the figures[...]
> 
> I am also a fan of using AsciiDoc as a documentation format. A
> while back I did some of the XSL hacking Mike refers to that is needed
> to get a decent conversion from the existing DocBook files. It's to
> the point where I would like to get some feedback.
> 
> I've done a first-pass conversion of the English version of the T & CG to
> AsciiDoc at https://github.com/codesmythe/gnucash-docs/tree/asciidoc/guide/C
> .
> You can click on the *.asc files there like ch_oview.asc to see GitHub's
> rendered verison of the file, including non-SVG images. (Note that SVG files
> and inter-chapter links don't work on GitHub's render.) You can click on the
> 'Raw' button for a file to see the AsciiDoc source. The source needs  clean
> up
> (lines too long, etc), but it is clean enough for folks to get an idea of
> the
> syntax. The GitHub web interace is useful because I think small edits could
> be
> done and sent as pull requests all from the web.
> 
> Like Mike said, the AsciiDoc tools (asciidoctor, at http://asciidoctor.org
> in
> this case) support the generation of DocBook XML files, so it's relatively
> simple to insert AsciiDoc support into the  current document generation
> flow.
> The asciidoctor tool generates DocBook output, and the existing flow for
> generating PDFs, HTML, EPUB, MOBI etc. works the same. My branch has the
> changes to the various Makefile.am files to support this. Those interested
> should be able to clone the repo, switch to the asciidoc branch and then
> 'make
> pdf' as usual. Note that the 'configure' script will expect to find the
> asciidoctor program on the system. I think the generated PDF is reasonably
> close to the original for a first pass proof of concept.  I've tested the
> flow
> on OS X and Fedora 21. Dunno about Windows.
> 
> Hopefully this little demo can move the documentation file format
> discussion
> forward a bit. :-) Thoughts?
> 
> 
> Regards,
> 
> Rob

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=0x00CDB13500D7AB53  
___
gnucash-devel mailing list
gnucash-devel@gnucash.org
https://lists.gnucash.org/mailman/listinfo/gnucash-devel

Using AsciiDoc for Documentation

[Rob Gowin]

[Hello List. Long time GnuCash user, -devel list lurker,
 coming out of the shadows.]

 On Aug 29, 2015, at 5:43 AM, Mike Evans mi...@saxicola.co.uk wrote:
 Another random thought then.

 I use asciidoc for pretty much all the docs I write, not much
 admittedly but it's easy to learn and can produce many output formats.
 I just used https://github.com/oreillymedia/docbook2asciidoc to
 convert the guide to asciidoc using:

 $ java -jar /home/mikee/Projects/docbook2asciidoc/saxon9he.jar
 -s gnucash-guide.xml -o gnucash-guide.asc
 /home/mikee/Projects/docbook2asciidoc/d2a.xsl  chunk-output=true

 This produces an asccidoc file for each chapter plus the master page.

 [...]

 I'm not an expert on XML parsing using .xsl stylesheets but I suspect
 this could be easily(?) remedied by editing the d2a.xsl to correctly
 include the figures[...]

I am also a fan of using AsciiDoc as a documentation format. A
while back I did some of the XSL hacking Mike refers to that is needed
to get a decent conversion from the existing DocBook files. It's to
the point where I would like to get some feedback.

I've done a first-pass conversion of the English version of the T  CG to
AsciiDoc at https://github.com/codesmythe/gnucash-docs/tree/asciidoc/guide/C
.
You can click on the *.asc files there like ch_oview.asc to see GitHub's
rendered verison of the file, including non-SVG images. (Note that SVG files
and inter-chapter links don't work on GitHub's render.) You can click on the
'Raw' button for a file to see the AsciiDoc source. The source needs  clean
up
(lines too long, etc), but it is clean enough for folks to get an idea of
the
syntax. The GitHub web interace is useful because I think small edits could
be
done and sent as pull requests all from the web.

Like Mike said, the AsciiDoc tools (asciidoctor, at http://asciidoctor.org
in
this case) support the generation of DocBook XML files, so it's relatively
simple to insert AsciiDoc support into the  current document generation
flow.
The asciidoctor tool generates DocBook output, and the existing flow for
generating PDFs, HTML, EPUB, MOBI etc. works the same. My branch has the
changes to the various Makefile.am files to support this. Those interested
should be able to clone the repo, switch to the asciidoc branch and then
'make
pdf' as usual. Note that the 'configure' script will expect to find the
asciidoctor program on the system. I think the generated PDF is reasonably
close to the original for a first pass proof of concept.  I've tested the
flow
on OS X and Fedora 21. Dunno about Windows.

Hopefully this little demo can move the documentation file format
discussion
forward a bit. :-) Thoughts?


Regards,

Rob
___
gnucash-devel mailing list
gnucash-devel@gnucash.org
https://lists.gnucash.org/mailman/listinfo/gnucash-devel