Documentation

David T. sunfish62 at yahoo.com
Wed Dec 11 13:22:25 EST 2013


John—

I’ll note that the GnuCash website Writing Documentation page, and it still includes all the information that scared David C. away (me too, I’ll add). Moreover, the directions there are all svn-based. Is there a clear and simple outline of the git process for documentation that us non-programmers can daily follow? To date, I have avoided the DocBook cycle in favor of placing my corrections into comments on Bugzilla and relied on others to migrate my edits into the actual documentation. If there really were a simple method for editing, that functions more like a word processor rather than a programming platform, it might broaden the documentation team.

David

On Dec 11, 2013, at 7:17 AM, John Ralls <jralls at ceridwen.us> wrote:

> 
> On Dec 11, 2013, at 6:05 AM, David Carlson <carlson.dl at sbcglobal.net> wrote:
> 
>> On 12/10/2013 10:27 PM, John Ralls wrote:
>>> On Dec 10, 2013, at 6:48 PM, David Carlson <carlson.dl at sbcglobal.net> wrote:
>>> 
>>>> On 12/10/2013 12:40 PM, John Ralls wrote:
>>>>> As we get down to the wire for releasing GnuCash 2.6, we still have 45 open documentation bugs. You can see the list at http://tinyurl.com/q6y4jvt; each bug on that list is a clickable link to the details.
>>>>> 
>>>>> If you’ve been looking for a way to contribute to Gnucash (or even if you haven’t ;-) ) but can’t contribute code for whatever reason, working on the documentation would be an excellent way to help.
>>>>> 
>>>>> Following the Gnome practice we use DocBook. Gnome has a nice manual for writing documentation, including DocBook, at https://developer.gnome.org/gdp-handbook/stable/. 
>>>> I just took another look at that DocBook reference and got overwhelmed
>>>> again by references to using multiple programs that do not run in
>>>> Windows, SVN, stylesheets, XML, etc., which reminds me of why I have
>>>> been submitting my documentation requests (several of those 45) in plain
>>>> text.  That seems to be where they end, because I am not ready to spend
>>>> several weeks learning how to get those programs running, etc.  If
>>>> someone knows how to convert text into appropriate XML with valid tags,
>>>> etc., I wish they would go ahead and do it.  Then I could let loose with
>>>> a whole bunch of additional documentation bugs.
>>>> 
>>> Have a go with this:
>>> http://www.openoffice.org/xml/xmerge/docbook/
>>> 
>>> It's not exactly a direct conversion of text, but if you can get it to work it'll be a lot easier than wrangling XML directly. 
>>> 
>>> Another possibility: https://fedoraproject.org/wiki/Converting_wiki_to_DocBook_XML?rd=DocsProject/Wiki2XML
>>> 
>>> We might be able to write a script to pull from the wiki. In the meantime, it suggests a temporary solution: Put your suggestions into the wiki. That way they'll be formatted and accessible. If we can't manage anything else we can put a pointer in the docs.
>>> 
>>> Regards,
>>> John Ralls
>>> 
>>> 
>> (When I was in college, I was the kid that sat in the front row of the
>> classroom and asked too many difficult questions.)
>> 
> 
> Me, too.
> 
>> Before I go too far with this, I have a big Question.
>> 
>> What about version control?
>> 
>> It appears that the Open Office path is designed to produce finished
>> documents as opposed to patches.  I think that the process of importing
>> a large XML document into OO, massaging it then exporting it back to XML
>> has a potential to wreak havoc. 
>> 
>> If that is true, an attempt to change or insert a few paragraphs or to
>> correct a singular mis-spelling would potentially create more work
>> rather than less work to push it into whichever version control system
>> that GnuCash is currently using for documentation.  Is that true, or am
>> I completely ignorant about how version control works?
> 
>> 
>> Is it possible to start an edit session in OO with a minimum amount of
>> context to identify correct placement of the edit in the overall document?
>> 
>> Also, I would not want to bypass the Bugzilla step in the process that
>> gives others a chance to stop me if I start down a wrong path.
>> 
>> I didn't even touch the issue of translation into foreign languages, did
>> I?  Oops, now I did. :)
>> 
>> To date I have not attempted to edit the wiki.  It looks like I need to
>> explore that path.
> 
> David,
> 
> Get TortoiseGit from http://code.google.com/p/tortoisegit/. It has a nice GUI that makes git pretty intuitive to those steeped in the Microsoft Way.
> 
> The way VC works is that you start with a file that git (I'm going to say git; all VC programs do more-or-less the same thing, but it's easier to type 'git' than 'the VC program' all the time) knows about, because you used git to put it on your system in the first place. You open the file and change it, then save the results. Git notices that the file is changed, and can show you the changes. You commit the changes, and in git's case your local git now recognizes the new state of the file and has stored the changes in its database so that it can go back to the old version if you want. You tell git to put the changes into a patch file which you then attach to the appropriate bug report. 
> 
> Someone with push privileges then retrieves your patch file from the bug, tells his local git repo to apply it, and pushes it to the master repository so that everyone can see it.
> 
> Git (and its distributed cousins Mercurial and Bazaar) are especially nice for individual users because there's no need for a master repository. You can version control any text file on your system with very little hassle. Once you start using it you may find uses that have nothing to do with programming: Lots of Linux users version control their configuration directories so that they can easily log and revert changes.
> 
> As for translation, don't worry about it. Once the revised text is in the repo, the translators will eventually see the changes and translate them.
> 
> Regards,
> John Ralls
> 
> 
> _______________________________________________
> gnucash-devel mailing list
> gnucash-devel at gnucash.org
> https://lists.gnucash.org/mailman/listinfo/gnucash-devel




More information about the gnucash-devel mailing list