[GNC-dev] Register Documentation Improvements (was Re: [GNC] Column widths again)

classic Classic list List threaded Threaded
36 messages Options
12
Reply | Threaded
Open this post in threaded view
|

Re: [GNC-dev] Register Documentation Improvements (was Re: [GNC] Column widths again)

Geert Janssens-4
Op donderdag 23 augustus 2018 15:08:54 CEST schreef Derek Atkins:

> Geert Janssens <[hidden email]> writes:
>
> [snip]
>
> > So I'm open for alternatives that would equally handle version
> > control, but is easier for documentation writers to cope with.
> >
> > This can be a completely different tool that feels more intuitive or
> > it can be a system layered on top of git which would hide git's
> > technicalities. For example a web interface that offers online
> > documentation editing and that behind the scenes stores changes in
> > git. I don't know of such project off-hand though, but it may be worth
> > looking around for.
> >
> > Those who need more advanced access can clone the git repo and work
> > locally.
> I wonder how hard it would be to write a web interface on top of git
> that abstracts away most of the git work to enable easier access?
>
> -derek

It looks like gitlab does something like this already...

At least on Gnome's gitlab there are buttons to edit or open a webide. They
only work on pages you have write access of course. However you can always
fork a repo to get one with write access.

Geert


_______________________________________________
gnucash-devel mailing list
[hidden email]
https://lists.gnucash.org/mailman/listinfo/gnucash-devel
Reply | Threaded
Open this post in threaded view
|

Re: [GNC-dev] Register Documentation Improvements (was Re: [GNC] Column widths again)

John Ralls-2


> On Aug 23, 2018, at 6:37 AM, Geert Janssens <[hidden email]> wrote:
>
> Op donderdag 23 augustus 2018 15:08:54 CEST schreef Derek Atkins:
>> Geert Janssens <[hidden email]> writes:
>>
>> [snip]
>>
>>> So I'm open for alternatives that would equally handle version
>>> control, but is easier for documentation writers to cope with.
>>>
>>> This can be a completely different tool that feels more intuitive or
>>> it can be a system layered on top of git which would hide git's
>>> technicalities. For example a web interface that offers online
>>> documentation editing and that behind the scenes stores changes in
>>> git. I don't know of such project off-hand though, but it may be worth
>>> looking around for.
>>>
>>> Those who need more advanced access can clone the git repo and work
>>> locally.
>> I wonder how hard it would be to write a web interface on top of git
>> that abstracts away most of the git work to enable easier access?
>>
>> -derek
>
> It looks like gitlab does something like this already...
>
> At least on Gnome's gitlab there are buttons to edit or open a webide. They
> only work on pages you have write access of course. However you can always
> fork a repo to get one with write access.

So does GitHub (it’s the pencil icon to the right of Raw/Blame/History), which also has a desktop front-end, https://desktop.github.com/ <https://desktop.github.com/> and a button on a file’s webpage that opens the file in Github Desktop.

I haven’t tried any of them, but perhaps David T. might like to and give us a non-developer perspective.

Regards,
John Ralls
_______________________________________________
gnucash-devel mailing list
[hidden email]
https://lists.gnucash.org/mailman/listinfo/gnucash-devel
Reply | Threaded
Open this post in threaded view
|

Re: [GNC-dev] Register Documentation Improvements (was Re: [GNC] Column widths again)

Adrien Monteleone-2
In reply to this post by Geert Janssens-4

> On Aug 23, 2018, at 3:00 AM, Geert Janssens <[hidden email]> wrote:
>
> Op dinsdag 21 augustus 2018 21:36:58 CEST schreef John Ralls:
>>> On Aug 21, 2018, at 11:50 AM, Geert Janssens <[hidden email]>
>>> wrote:
>>> Aside from that they also expect there writers to work with git.
>>
>> Version control is an obvious hard requirement. I don't know if it
>> completely fulfills your "manageability" requirement, but it's crucial in a
>> collaborative environment to be able to track who-did-what-when and to be
>> able to restore an earlier version if something goes awry.
>>
> In my requirements I deliberately wrote "manageability". Today we use git for
> this and from my developer's point of view it has all the features we need. So
> I consider it an excellent candidate. Unfortunately most non-developers
> experience it as a major hurdle.
>
> So I'm open for alternatives that would equally handle version control, but is
> easier for documentation writers to cope with.
>
> This can be a completely different tool that feels more intuitive or it can be
> a system layered on top of git which would hide git's technicalities. For
> example a web interface that offers online documentation editing and that
> behind the scenes stores changes in git. I don't know of such project off-hand
> though, but it may be worth looking around for.

Such a thing does exist.

I’ve been investigating this for some client projects that use Wordpress. There are plugins that interface with git for version control both for the site as a whole and for specific pages/posts. Wordpress itself has a revisions control built in, though it doesn’t work with git out of the box, you can see who made what changes and revert specific ones if needed.

I think I also found some time ago that Wikimedia has plugins for generating the needed formats.

Regards,
Adrien


> Those who need more advanced access can clone the git repo and work locally.
>
>
>> That said I'm perfectly happy to copy a rewritten section of a document into
>> my working directory and create a commit out of it on behalf of a
>> non-technical author who can't get their head around git.
>
> Of course. Same for me. Anything that lowers the barrier.
>
> Geert
>
>
> _______________________________________________
> gnucash-devel mailing list
> [hidden email]
> https://lists.gnucash.org/mailman/listinfo/gnucash-devel
>


_______________________________________________
gnucash-devel mailing list
[hidden email]
https://lists.gnucash.org/mailman/listinfo/gnucash-devel
Reply | Threaded
Open this post in threaded view
|

Re: [GNC-dev] Register Documentation Improvements (was Re: [GNC] Column widths again)

John Ralls-2
In reply to this post by Geert Janssens-4


> On Aug 23, 2018, at 12:45 AM, Geert Janssens <[hidden email]> wrote:
>
> Op dinsdag 21 augustus 2018 21:24:25 CEST schreef John Ralls:
>>> On Aug 21, 2018, at 11:50 AM, Geert Janssens <[hidden email]>
>>> wrote: - it should allow multiple output formats. A few the come to mind:
>>> html, pdf, epub, mobi, windows compressed help, xml for yelp,...
>>
>> We don't need a single tool to do that; in fact we don't use a single tool
>> now. We create Windows compressed html (.chm) with HTML Help Workshop from
>> the xslt-created HTML and mobi with calibre from the xslt-created epub.
>>
> It appears while writing down the requirements, I was more considering our
> documentation system as a whole, not just a single tool. I agree this can
> consist of several tools glued together.
>
> I think what matters is the people actually writing the documentation should
> have to learn as few as possible to keep the barrier for contribution very
> low. More on that in reply to your other message.
>
>> That aside, I think we should reconsider windows compressed help.
>> Microsoft's own Windows 10 applications seem to open the browser to the
>> relevant documentation page on www.microsoft.com and the help browser is
>> still decorated with Windows 2000 frame and controls. It looks quite
>> jarring. We could more easily just open the documents in a GtkWebkitWebView
>> just like reports.
>
> I'm all for this. In fact I have proposed this in the past. That also rids us
> of one of the more annoying build dependencies on Windows (HtmlHelp).
>
> It would be nice if our html version of the docs would get some css love in
> that case though. Wading through plain rendered html is an equally 2000'ish
> experience.

I've been having another look at https://pandoc.org/. It consumes several flavors of markdown and wiki markup as well as DocBook. It emits an impressive range of output formats including DocBook, GNU texinfo (which is completely unrelated to TeX), LaTeX, HTML, and Epub; the only deficiency from our view would be that it doesn't directly emit PDF. It can do so indirectly via LaTeX or we could generate DocBook and continue to use Apache XML-Format-Objects.

My original thought was that contributors could use it to convert the current DocBook sources to Microsoft Word or LibreOffice format, edit in a familiar word processor, and then use pandoc to convert back to DocBook. That didn't work out very well in testing.

So a new thought: One of the core devs use pandoc to convert the DocBook source to one of the markup/markdown variants, do the necessary manual fixups and commit the result. If we want DocBook for some reason the build process would use pandoc to generate it.

If we had GitHub-flavored markdown sources then https://github.com/gnucash/gnucash-docs would show rendered documentation and one could use the "preview" button to check basic layout; it would appear pretty similar to how the document would look in a PDF or eBook rendering.

Regards,
John Ralls

_______________________________________________
gnucash-devel mailing list
[hidden email]
https://lists.gnucash.org/mailman/listinfo/gnucash-devel
Reply | Threaded
Open this post in threaded view
|

Re: [GNC-dev] Register Documentation Improvements (was Re: [GNC] Column widths again)

John Ralls-2
In reply to this post by Geert Janssens-4


> On Aug 23, 2018, at 12:37 AM, Geert Janssens <[hidden email]> wrote:
>
> Op dinsdag 21 augustus 2018 20:50:38 CEST schreef Geert Janssens:
>> Op dinsdag 21 augustus 2018 17:49:57 CEST schreef Adrien Monteleone:
>>> but is there a list of ’needs’ of the
>>> developers to use when evaluating methods?
>>
>> I don't think it's ever been formally written down. But here is a first
>> list:
>>
>> - it should be as easy as possible to use by non-technical people
>> - it should allow multiple output formats. A few the come to mind:
>> html, pdf, epub, mobi, windows compressed help, xml for yelp,...
>> - it should support both on-screen output as printable output. This is
>> mostly relevant for image resolutions.
>> - it should support the usual typical documentation constructs, like
>> chapters, sections, subsections, indexes, links, tables, images,...
>> - it should be manageable. That is there should be mechanisms to support
>> multiple versions of one document simultaneously. A typical use case is that
>> some feature gets documented that is in both the current version and the
>> future one, so this document snippet should be in both versions of the
>> documentation as well. While a snippet that's only for the newer version
>> should only be in the future version of the documentation. And after a few
>> months it should still be obvious which snippets have been integrated in
>> which versions.
>> - I would like to see a WYSIWYM ("what you see is what you mean") kind of
>> editor for the documentation process.
>>
>> This is non-exhaustive and I expect the other developers may have even more
>> requirements.
>>
> Add a way to relatively easily manage translations of the documentation.

That's almost a new subject entirely. Except for Italian, the "translated" documents are more like "rewritten in another language". I think that's a good thing because it affords a more natural, idiomatic experience to readers, but I imagine (I have to imagine, I'm nowhere near fluent enough in any language other than English to have experience) that it's also more work on the part of the foreign-language authors.

The alternative is to run gettext on the doc sources and have a po file for the translation. Cristian Marchi set that up for Italian, but it has an unfortunate side effect: If the translation isn't kept up to date with the documentation progressively more of it becomes "fuzzy" and reverts to English. I tried for a while to do fresh it.po builds, but it was soon clear that it was a bad idea and so we're back to using a mostly frozen, monolithic, it/gnucash-guide.xml and it/gnucash-help.xml from 2.4.

Regards,
John Ralls

_______________________________________________
gnucash-devel mailing list
[hidden email]
https://lists.gnucash.org/mailman/listinfo/gnucash-devel
Reply | Threaded
Open this post in threaded view
|

Re: [GNC-dev] Register Documentation Improvements (was Re: [GNC] Column widths again)

Rob Gowin
In reply to this post by John Ralls-2
On Thu, Aug 23, 2018 at 11:40 AM, John Ralls <[hidden email]> wrote:

>
>
> So a new thought: One of the core devs use pandoc to convert the DocBook
> source to one of the markup/markdown variants, do the necessary manual
> fixups and commit the result. If we want DocBook for some reason the build
> process would use pandoc to generate it.
>
> If we had GitHub-flavored markdown sources then
> https://github.com/gnucash/gnucash-docs would show rendered documentation
> and one could use the "preview" button to check basic layout; it would
> appear pretty similar to how the document would look in a PDF or eBook
> rendering.
>
>
Hmmm. Old thought. :-) I did all of this in the 2015 thread that Geert
referenced. (Except I did not use pandoc, and used Asciidoc has my markup
variant of choice.) A rendered version of the Tutorial and Concept Guide
can be found here: https://github.com/codesmythe/gnucash-guide-asciidoc.
For example, click on 'en' then on ch_cbook.adoc to see a rendered version.
Then on that page click on the 'Raw' to see the Asciidoc source. I'd also
worked out the flow changes to generate PDF, eBook, etc from the Asciidoc
sources.

In
https://lists.gnucash.org/pipermail/gnucash-devel/2015-September/038997.html,
you asked for buy-in from the non-tech doc writers, and unfortunately, none
was found. :-(

One thing that has changed in the interim is the availability of decent
editors that have a live-preview mode that will show the raw Asciidoc on
the left and the live-rendered result on the right. For example, Visual
Studio Code (available for Mac, Linux, Windows) has an extension for this:
https://marketplace.visualstudio.com/items?itemName=joaompinto.asciidoctor-vscode
(see the demo gif), and VS Code supports Git out of the box.

Rob
_______________________________________________
gnucash-devel mailing list
[hidden email]
https://lists.gnucash.org/mailman/listinfo/gnucash-devel
Reply | Threaded
Open this post in threaded view
|

Re: [GNC-dev] Register Documentation Improvements (was Re: [GNC] Column widths again)

John Ralls-2


> On Aug 23, 2018, at 10:25 AM, Rob Gowin <[hidden email]> wrote:
>
>
> On Thu, Aug 23, 2018 at 11:40 AM, John Ralls <[hidden email]> wrote:
>
>
> So a new thought: One of the core devs use pandoc to convert the DocBook source to one of the markup/markdown variants, do the necessary manual fixups and commit the result. If we want DocBook for some reason the build process would use pandoc to generate it.
>
> If we had GitHub-flavored markdown sources then https://github.com/gnucash/gnucash-docs would show rendered documentation and one could use the "preview" button to check basic layout; it would appear pretty similar to how the document would look in a PDF or eBook rendering.
>
>
> Hmmm. Old thought. :-) I did all of this in the 2015 thread that Geert referenced. (Except I did not use pandoc, and used Asciidoc has my markup variant of choice.) A rendered version of the Tutorial and Concept Guide can be found here: https://github.com/codesmythe/gnucash-guide-asciidoc. For example, click on 'en' then on ch_cbook.adoc to see a rendered version. Then on that page click on the 'Raw' to see the Asciidoc source. I'd also worked out the flow changes to generate PDF, eBook, etc from the Asciidoc sources.
>
> In https://lists.gnucash.org/pipermail/gnucash-devel/2015-September/038997.html, you asked for buy-in from the non-tech doc writers, and unfortunately, none was found. :-(
>
> One thing that has changed in the interim is the availability of decent editors that have a live-preview mode that will show the raw Asciidoc on the left and the live-rendered result on the right. For example, Visual Studio Code (available for Mac, Linux, Windows) has an extension for this: https://marketplace.visualstudio.com/items?itemName=joaompinto.asciidoctor-vscode (see the demo gif), and VS Code supports Git out of the box.

Rob,

Thanks, I'd forgotten about that. I just tested and Github's online editor is able to render the adoc, so from that standpoint it's equivalent. Since it's supposed to be fully compatible with DocBook (though it requires an external tool like pandoc to convert from DocBook to Asciidoc) it will be a better fit with the existing sources that would any of the other plain-text markup choices.

What about it, (potential) documenters? Is any markup language acceptable or does the solution have to be WYSIWYG with buttons and menus for styling?

Regards,
John Ralls

_______________________________________________
gnucash-devel mailing list
[hidden email]
https://lists.gnucash.org/mailman/listinfo/gnucash-devel
Reply | Threaded
Open this post in threaded view
|

Re: [GNC-dev] Register Documentation Improvements (was Re: [GNC] Column widths again)

sunfish62
In reply to this post by John Ralls-2
Hmm.

Let me see if I understand this correctly. You’re saying that I could make edits on my own forked copy of gnucash-docs, save those changes, and get them to the official gnucash-docs *all from the github website*?

*If* I understand it correctly, then this would be a big improvement from my perspective. After all, I’ve never objected to adding the obscure codes; it’s always been getting the changes in. It does sound promising, but I hesitate to take it on, simply because at this point, I am a trained hamster who knows how to get a result in one way and one way only.

I will look for a simple doc update to try it out on; that way, when I miraculously find the one way to screw it up, it won’t be difficult to remove.

David

> On Aug 23, 2018, at 9:55 AM, John Ralls <[hidden email]> wrote:
>
>
>
>> On Aug 23, 2018, at 6:37 AM, Geert Janssens <[hidden email]> wrote:
>>
>> Op donderdag 23 augustus 2018 15:08:54 CEST schreef Derek Atkins:
>>> Geert Janssens <[hidden email]> writes:
>>>
>>> [snip]
>>>
>>>> So I'm open for alternatives that would equally handle version
>>>> control, but is easier for documentation writers to cope with.
>>>>
>>>> This can be a completely different tool that feels more intuitive or
>>>> it can be a system layered on top of git which would hide git's
>>>> technicalities. For example a web interface that offers online
>>>> documentation editing and that behind the scenes stores changes in
>>>> git. I don't know of such project off-hand though, but it may be worth
>>>> looking around for.
>>>>
>>>> Those who need more advanced access can clone the git repo and work
>>>> locally.
>>> I wonder how hard it would be to write a web interface on top of git
>>> that abstracts away most of the git work to enable easier access?
>>>
>>> -derek
>>
>> It looks like gitlab does something like this already...
>>
>> At least on Gnome's gitlab there are buttons to edit or open a webide. They
>> only work on pages you have write access of course. However you can always
>> fork a repo to get one with write access.
>
> So does GitHub (it’s the pencil icon to the right of Raw/Blame/History), which also has a desktop front-end, https://desktop.github.com/ <https://desktop.github.com/> and a button on a file’s webpage that opens the file in Github Desktop.
>
> I haven’t tried any of them, but perhaps David T. might like to and give us a non-developer perspective.
>
> Regards,
> John Ralls
> _______________________________________________
> gnucash-devel mailing list
> [hidden email]
> https://lists.gnucash.org/mailman/listinfo/gnucash-devel

_______________________________________________
gnucash-devel mailing list
[hidden email]
https://lists.gnucash.org/mailman/listinfo/gnucash-devel
Reply | Threaded
Open this post in threaded view
|

Re: [GNC-dev] Register Documentation Improvements (was Re: [GNC] Column widths again)

John Ralls-2
David,

It’s git. It’s never difficult to remove stuff, but on the website there’s no reflow to get back what you’ve deleted, so take a  little more care than usual. (Well, there is, but not from the web interface: https://medium.com/git-tips/githubs-reflog-a9ff21ff765f <https://medium.com/git-tips/githubs-reflog-a9ff21ff765f>)

You’ve already got a clone and you made a PR a week ago, so you’re most of the way there already.

{Optional} Create a branch in your repo on the website: Click on the “branch” drop down and enter a new branch name.

Now pick a file and click on the pencil. Make an edit or two. Scroll to the bottom where you’ll find two edit boxes, one for the commit summary and another for a detailed message and a radio to commit your changes or to create a new branch and a PR all in one go, which is why I marked “create a branch” as optional.

This method creates one commit per file. If your change is more complex and you want to have edits of more than one file in a single commit, there’s a work-around at https://stackoverflow.com/questions/17815895/can-i-edit-two-files-then-make-one-commit-using-github-web-based-editor <https://stackoverflow.com/questions/17815895/can-i-edit-two-files-then-make-one-commit-using-github-web-based-editor>.

When you’re done playing, just change the branch back to master and click the “# branches”  in the bar on the root page. You’ll get a list of current branches with a red trash can on the right side. Click the trash can to delete your play branch.

Regards,
John Ralls


> On Aug 23, 2018, at 2:44 PM, David T. <[hidden email]> wrote:
>
> Hmm.
>
> Let me see if I understand this correctly. You’re saying that I could make edits on my own forked copy of gnucash-docs, save those changes, and get them to the official gnucash-docs *all from the github website*?
>
> *If* I understand it correctly, then this would be a big improvement from my perspective. After all, I’ve never objected to adding the obscure codes; it’s always been getting the changes in. It does sound promising, but I hesitate to take it on, simply because at this point, I am a trained hamster who knows how to get a result in one way and one way only.
>
> I will look for a simple doc update to try it out on; that way, when I miraculously find the one way to screw it up, it won’t be difficult to remove.
>
> David
>
>> On Aug 23, 2018, at 9:55 AM, John Ralls <[hidden email]> wrote:
>>
>>
>>
>>> On Aug 23, 2018, at 6:37 AM, Geert Janssens <[hidden email]> wrote:
>>>
>>> Op donderdag 23 augustus 2018 15:08:54 CEST schreef Derek Atkins:
>>>> Geert Janssens <[hidden email]> writes:
>>>>
>>>> [snip]
>>>>
>>>>> So I'm open for alternatives that would equally handle version
>>>>> control, but is easier for documentation writers to cope with.
>>>>>
>>>>> This can be a completely different tool that feels more intuitive or
>>>>> it can be a system layered on top of git which would hide git's
>>>>> technicalities. For example a web interface that offers online
>>>>> documentation editing and that behind the scenes stores changes in
>>>>> git. I don't know of such project off-hand though, but it may be worth
>>>>> looking around for.
>>>>>
>>>>> Those who need more advanced access can clone the git repo and work
>>>>> locally.
>>>> I wonder how hard it would be to write a web interface on top of git
>>>> that abstracts away most of the git work to enable easier access?
>>>>
>>>> -derek
>>>
>>> It looks like gitlab does something like this already...
>>>
>>> At least on Gnome's gitlab there are buttons to edit or open a webide. They
>>> only work on pages you have write access of course. However you can always
>>> fork a repo to get one with write access.
>>
>> So does GitHub (it’s the pencil icon to the right of Raw/Blame/History), which also has a desktop front-end, https://desktop.github.com/ <https://desktop.github.com/> and a button on a file’s webpage that opens the file in Github Desktop.
>>
>> I haven’t tried any of them, but perhaps David T. might like to and give us a non-developer perspective.
>>
>> Regards,
>> John Ralls
>> _______________________________________________
>> gnucash-devel mailing list
>> [hidden email]
>> https://lists.gnucash.org/mailman/listinfo/gnucash-devel
>

_______________________________________________
gnucash-devel mailing list
[hidden email]
https://lists.gnucash.org/mailman/listinfo/gnucash-devel
Reply | Threaded
Open this post in threaded view
|

Re: [GNC-dev] Register Documentation Improvements (was Re: [GNC] Column widths again)

GnuCash - Dev mailing list
In reply to this post by Adrien Monteleone-2
So. I just tried this out on bug 791169. I believe it worked?

On August 23, 2018, at 11:47 PM, John Ralls <[hidden email]> wrote:

David,


It’s git. It’s never difficult to remove stuff, but on the website there’s no reflow to get back what you’ve deleted, so take a  little more care than usual. (Well, there is, but not from the web interface: https://medium.com/git-tips/githubs-reflog-a9ff21ff765f)


You’ve already got a clone and you made a PR a week ago, so you’re most of the way there already.


{Optional} Create a branch in your repo on the website: Click on the “branch” drop down and enter a new branch name.


Now pick a file and click on the pencil. Make an edit or two. Scroll to the bottom where you’ll find two edit boxes, one for the commit summary and another for a detailed message and a radio to commit your changes or to create a new branch and a PR all in one go, which is why I marked “create a branch” as optional.


This method creates one commit per file. If your change is more complex and you want to have edits of more than one file in a single commit, there’s a work-around at https://stackoverflow.com/questions/17815895/can-i-edit-two-files-then-make-one-commit-using-github-web-based-editor.


When you’re done playing, just change the branch back to master and click the “# branches”  in the bar on the root page. You’ll get a list of current branches with a red trash can on the right side. Click the trash can to delete your play branch.


Regards,

John Ralls



On Aug 23, 2018, at 2:44 PM, David T. <[hidden email]> wrote:


Hmm.

Let me see if I understand this correctly. You’re saying that I could make edits on my own forked copy of gnucash-docs, save those changes, and get them to the official gnucash-docs *all from the github website*?

*If* I understand it correctly, then this would be a big improvement from my perspective. After all, I’ve never objected to adding the obscure codes; it’s always been getting the changes in. It does sound promising, but I hesitate to take it on, simply because at this point, I am a trained hamster who knows how to get a result in one way and one way only.

I will look for a simple doc update to try it out on; that way, when I miraculously find the one way to screw it up, it won’t be difficult to remove.

David

On Aug 23, 2018, at 9:55 AM, John Ralls <[hidden email]> wrote:



On Aug 23, 2018, at 6:37 AM, Geert Janssens <[hidden email]> wrote:

Op donderdag 23 augustus 2018 15:08:54 CEST schreef Derek Atkins:

Geert Janssens <[hidden email]> writes:

[snip]

So I'm open for alternatives that would equally handle version
control, but is easier for documentation writers to cope with.

This can be a completely different tool that feels more intuitive or
it can be a system layered on top of git which would hide git's
technicalities. For example a web interface that offers online
documentation editing and that behind the scenes stores changes in
git. I don't know of such project off-hand though, but it may be worth
looking around for.

Those who need more advanced access can clone the git repo and work
locally.

I wonder how hard it would be to write a web interface on top of git
that abstracts away most of the git work to enable easier access?

-derek


It looks like gitlab does something like this already...

At least on Gnome's gitlab there are buttons to edit or open a webide. They
only work on pages you have write access of course. However you can always
fork a repo to get one with write access.


So does GitHub (it’s the pencil icon to the right of Raw/Blame/History), which also has a desktop front-end, https://desktop.github.com/ <https://desktop.github.com/> and a button on a file’s webpage that opens the file in Github Desktop.

I haven’t tried any of them, but perhaps David T. might like to and give us a non-developer perspective.

Regards,
John Ralls
_______________________________________________
gnucash-devel mailing list
[hidden email]
https://lists.gnucash.org/mailman/listinfo/gnucash-devel



_______________________________________________
gnucash-devel mailing list
[hidden email]
https://lists.gnucash.org/mailman/listinfo/gnucash-devel
Reply | Threaded
Open this post in threaded view
|

Re: [GNC-dev] Register Documentation Improvements (was Re: [GNC]Column widths again)

Christopher Lam
In reply to this post by John Ralls-2
> So does GitHub (it’s the pencil icon to the right of Raw/Blame/History), which also has a desktop front-end, https://desktop.github.com/ <https://desktop.github.com/> and a button on a file’s webpage that opens the file in Github Desktop.
> I haven’t tried any of them, but perhaps David T. might like to and give us a non-developer perspective.

I can confirm that 1 year ago I was hacking transaction.scm in Windows, using Notepad++, pasting changes into the GitHub.com web-based editor, checking edits using the Preview tab, until I learned enough command-line git, then emacs, then emacs-magit...
_______________________________________________
gnucash-devel mailing list
[hidden email]
https://lists.gnucash.org/mailman/listinfo/gnucash-devel
Reply | Threaded
Open this post in threaded view
|

Re: [GNC-dev] Register Documentation Improvements (was Re: [GNC] Column widths again)

John Ralls-2
In reply to this post by Geert Janssens-4


> On Aug 23, 2018, at 12:45 AM, Geert Janssens <[hidden email]> wrote:
>
> It would be nice if our html version of the docs would get some css love in
> that case though. Wading through plain rendered html is an equally 2000'ish
> experience.

I just had a look at https://github.com/Gnucash/gnucash-docs/tree/master/xsl <https://github.com/Gnucash/gnucash-docs/tree/master/xsl>. It’s pretty old, the docbook part is 1.75.2 from 2010 and the rest was lifted from an early Gnome docs beta and never updated. No wonder it looks like 2000’ish html, it *is* 2000’ish html!

We could go Gnome [1] or we could just use the latest stylesheets [2] from DocBook itself (tutorial [3]). Or we could do something else.

Regards,
John Ralls

[1] https://gitlab.gnome.org/GNOME/gnome-doc-utils <https://gitlab.gnome.org/GNOME/gnome-doc-utils>
[2] https://github.com/docbook/xslt10-stylesheets/ <https://github.com/docbook/xslt10-stylesheets/>, reference docs https://github.com/docbook/xslt10-stylesheets/tree/master/xsl/doc <https://github.com/docbook/xslt10-stylesheets/tree/master/xsl/doc>
[3] http://www.sagehill.net/docbookxsl/ <http://www.sagehill.net/docbookxsl/>
_______________________________________________
gnucash-devel mailing list
[hidden email]
https://lists.gnucash.org/mailman/listinfo/gnucash-devel
Reply | Threaded
Open this post in threaded view
|

Re: [GNC-dev] Register Documentation Improvements (was Re: [GNC] Column widths again)

Mike Evans-3
In reply to this post by Rob Gowin
On Thu, 23 Aug 2018 12:25:51 -0500
Rob Gowin <[hidden email]> wrote:

> On Thu, Aug 23, 2018 at 11:40 AM, John Ralls <[hidden email]> wrote:
>
> >
> >
> > So a new thought: One of the core devs use pandoc to convert the DocBook
> > source to one of the markup/markdown variants, do the necessary manual
> > fixups and commit the result. If we want DocBook for some reason the build
> > process would use pandoc to generate it.
> >
> > If we had GitHub-flavored markdown sources then
> > https://github.com/gnucash/gnucash-docs would show rendered documentation
> > and one could use the "preview" button to check basic layout; it would
> > appear pretty similar to how the document would look in a PDF or eBook
> > rendering.
> >
> >  
> Hmmm. Old thought. :-) I did all of this in the 2015 thread that Geert
> referenced. (Except I did not use pandoc, and used Asciidoc has my markup
> variant of choice.) A rendered version of the Tutorial and Concept Guide
> can be found here: https://github.com/codesmythe/gnucash-guide-asciidoc.
> For example, click on 'en' then on ch_cbook.adoc to see a rendered version.
> Then on that page click on the 'Raw' to see the Asciidoc source. I'd also
> worked out the flow changes to generate PDF, eBook, etc from the Asciidoc
> sources.
>
> In
> https://lists.gnucash.org/pipermail/gnucash-devel/2015-September/038997.html,
> you asked for buy-in from the non-tech doc writers, and unfortunately, none
> was found. :-(
>
> One thing that has changed in the interim is the availability of decent
> editors that have a live-preview mode that will show the raw Asciidoc on
> the left and the live-rendered result on the right. For example, Visual
> Studio Code (available for Mac, Linux, Windows) has an extension for this:
> https://marketplace.visualstudio.com/items?itemName=joaompinto.asciidoctor-vscode
> (see the demo gif), and VS Code supports Git out of the box.
>
> Rob
> _______________________________________________

Hi Rob

Referring to your mail of 2015-09-01 you "put the XSL file and a python
script to run the conversion process in a repository at
https://github.com/codesmythe/asciidoc-conversion."

This no longer exists, can you make it available again? Unless you'd rather not of course.

Mike Evans


--
GPG Key fingerprint = 0D8A 33A8 F7F8 733C 7519  2A56 DB8F 7CF1 C67B BC0F

_______________________________________________
gnucash-devel mailing list
[hidden email]
https://lists.gnucash.org/mailman/listinfo/gnucash-devel
Reply | Threaded
Open this post in threaded view
|

Re: [GNC-dev] Register Documentation Improvements (was Re: [GNC] Column widths again)

Rob Gowin
On Mon, Aug 27, 2018 at 7:50 AM, Mike Evans <[hidden email]> wrote:

>
> Hi Rob
>
> Referring to your mail of 2015-09-01 you "put the XSL file and a python
> script to run the conversion process in a repository at
> https://github.com/codesmythe/asciidoc-conversion."
>
> This no longer exists, can you make it available again? Unless you'd
> rather not of course.
>
> Mike Evans
>

And by not-so-popular demand, that repository is back. :-)

I haven't touched that code since the 2015 discussion, but hopefully you
can some use out of it.

Regards,

Rob
_______________________________________________
gnucash-devel mailing list
[hidden email]
https://lists.gnucash.org/mailman/listinfo/gnucash-devel
Reply | Threaded
Open this post in threaded view
|

Re: [GNC-dev] Register Documentation Improvements (was Re: [GNC] Column widths again)

Mike Evans-3
On Mon, 27 Aug 2018 11:14:28 -0500
Rob Gowin <[hidden email]> wrote:

> On Mon, Aug 27, 2018 at 7:50 AM, Mike Evans <[hidden email]> wrote:
> >
> > Hi Rob
> >
> > Referring to your mail of 2015-09-01 you "put the XSL file and a python
> > script to run the conversion process in a repository at
> > https://github.com/codesmythe/asciidoc-conversion."
> >
> > This no longer exists, can you make it available again? Unless you'd
> > rather not of course.
> >
> > Mike Evans
> >  
>
> And by not-so-popular demand, that repository is back. :-)
>
> I haven't touched that code since the 2015 discussion, but hopefully you
> can some use out of it.
>
> Regards,
>
> Rob

Forked. So now there are two.

Mike E
_______________________________________________
gnucash-devel mailing list
[hidden email]
https://lists.gnucash.org/mailman/listinfo/gnucash-devel
Reply | Threaded
Open this post in threaded view
|

Re: [GNC-dev] Documentation Source Format (was: Register Documentation Improvements)

John Ralls-2
In reply to this post by John Ralls-2


> On Aug 23, 2018, at 12:52 PM, John Ralls <[hidden email]> wrote:
>
>
>
>> On Aug 23, 2018, at 10:25 AM, Rob Gowin <[hidden email]> wrote:
>>
>>
>> On Thu, Aug 23, 2018 at 11:40 AM, John Ralls <[hidden email]> wrote:
>>
>>
>> So a new thought: One of the core devs use pandoc to convert the DocBook source to one of the markup/markdown variants, do the necessary manual fixups and commit the result. If we want DocBook for some reason the build process would use pandoc to generate it.
>>
>> If we had GitHub-flavored markdown sources then https://github.com/gnucash/gnucash-docs would show rendered documentation and one could use the "preview" button to check basic layout; it would appear pretty similar to how the document would look in a PDF or eBook rendering.
>>
>>
>> Hmmm. Old thought. :-) I did all of this in the 2015 thread that Geert referenced. (Except I did not use pandoc, and used Asciidoc has my markup variant of choice.) A rendered version of the Tutorial and Concept Guide can be found here: https://github.com/codesmythe/gnucash-guide-asciidoc. For example, click on 'en' then on ch_cbook.adoc to see a rendered version. Then on that page click on the 'Raw' to see the Asciidoc source. I'd also worked out the flow changes to generate PDF, eBook, etc from the Asciidoc sources.
>>
>> In https://lists.gnucash.org/pipermail/gnucash-devel/2015-September/038997.html, you asked for buy-in from the non-tech doc writers, and unfortunately, none was found. :-(
>>
>> One thing that has changed in the interim is the availability of decent editors that have a live-preview mode that will show the raw Asciidoc on the left and the live-rendered result on the right. For example, Visual Studio Code (available for Mac, Linux, Windows) has an extension for this: https://marketplace.visualstudio.com/items?itemName=joaompinto.asciidoctor-vscode (see the demo gif), and VS Code supports Git out of the box.
>
> Rob,
>
> Thanks, I'd forgotten about that. I just tested and Github's online editor is able to render the adoc, so from that standpoint it's equivalent. Since it's supposed to be fully compatible with DocBook (though it requires an external tool like pandoc to convert from DocBook to Asciidoc) it will be a better fit with the existing sources that would any of the other plain-text markup choices.
>
> What about it, (potential) documenters? Is any markup language acceptable or does the solution have to be WYSIWYG with buttons and menus for styling?

Frank opened a bug [1] about this in early 2014 after a lengthy discussion here, and Geert added a summary of the mailing list discussion. One pearl from that: The potential documenters of the day thought that Asciidoc was "still too difficult to learn for non-technical people".

Frank brought up another option on that bug today: Calibre [2], which can do conversions among a variety of formats. DocBook isn't one of them, but EPUB is and we generate EPUB from DocBook as part of the release process. It's also able to handle DOCX and ODT as an input format (as is pandoc), and it's able to edit EPUB (an HTML+CSS variant).

Perhaps one of the Davids would consider trying it out.

Regards,
John Ralls

[1] https://bugs.gnucash.org/show_bug.cgi?id=722016
[2] https://calibre-ebook.com/

_______________________________________________
gnucash-devel mailing list
[hidden email]
https://lists.gnucash.org/mailman/listinfo/gnucash-devel
12