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

[Mike Evans]

On Mon, 27 Aug 2018 11:14:28 -0500
Rob Gowin  wrote:

> On Mon, Aug 27, 2018 at 7:50 AM, Mike Evans  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
gnucash-devel@gnucash.org
https://lists.gnucash.org/mailman/listinfo/gnucash-devel

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  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
gnucash-devel@gnucash.org
https://lists.gnucash.org/mailman/listinfo/gnucash-devel

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

[Mike Evans]

On Thu, 23 Aug 2018 12:25:51 -0500
Rob Gowin  wrote:

> On Thu, Aug 23, 2018 at 11:40 AM, John Ralls  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
gnucash-devel@gnucash.org
https://lists.gnucash.org/mailman/listinfo/gnucash-devel

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

[John Ralls]

> On Aug 23, 2018, at 12:45 AM, Geert Janssens  
> 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 
. 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 

[2] https://github.com/docbook/xslt10-stylesheets/ 
, reference docs 
https://github.com/docbook/xslt10-stylesheets/tree/master/xsl/doc 

[3] http://www.sagehill.net/docbookxsl/ 
___
gnucash-devel mailing list
gnucash-devel@gnucash.org
https://lists.gnucash.org/mailman/listinfo/gnucash-devel

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

[Adrien Monteleone]

> On Aug 23, 2018, at 3:00 AM, Geert Janssens  
> wrote:
> 
> Op dinsdag 21 augustus 2018 21:36:58 CEST schreef John Ralls:
>>> On Aug 21, 2018, at 11:50 AM, Geert Janssens 
>>> 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
> gnucash-devel@gnucash.org
> https://lists.gnucash.org/mailman/listinfo/gnucash-devel
> 


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

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

[Christopher Lam]

> 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/ 
>  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
gnucash-devel@gnucash.org
https://lists.gnucash.org/mailman/listinfo/gnucash-devel

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

[D via gnucash-devel]

So. I just tried this out on bug 791169. I believe it worked?

On August 23, 2018, at 11:47 PM, John Ralls  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.  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  wrote:



On Aug 23, 2018, at 6:37 AM, Geert Janssens  wrote:

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

Geert Janssens  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/ 
 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
gnucash-devel@gnucash.org
https://lists.gnucash.org/mailman/listinfo/gnucash-devel



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

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

[John Ralls]

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.  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  wrote:
>> 
>> 
>> 
>>> On Aug 23, 2018, at 6:37 AM, Geert Janssens  
>>> wrote:
>>> 
>>> Op donderdag 23 augustus 2018 15:08:54 CEST schreef Derek Atkins:
 Geert Janssens  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/ 
>>  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
>> gnucash-devel@gnucash.org
>> https://lists.gnucash.org/mailman/listinfo/gnucash-devel
> 

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

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

[David T.]

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  wrote:
> 
> 
> 
>> On Aug 23, 2018, at 6:37 AM, Geert Janssens  
>> wrote:
>> 
>> Op donderdag 23 augustus 2018 15:08:54 CEST schreef Derek Atkins:
>>> Geert Janssens  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/ 
>  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
> gnucash-devel@gnucash.org
> https://lists.gnucash.org/mailman/listinfo/gnucash-devel

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

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

[John Ralls]

> On Aug 23, 2018, at 10:25 AM, Rob Gowin  wrote:
> 
> 
> On Thu, Aug 23, 2018 at 11:40 AM, John Ralls  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
gnucash-devel@gnucash.org
https://lists.gnucash.org/mailman/listinfo/gnucash-devel

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

[Rob Gowin]

On Thu, Aug 23, 2018 at 11:40 AM, John Ralls  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
gnucash-devel@gnucash.org
https://lists.gnucash.org/mailman/listinfo/gnucash-devel

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

[John Ralls]

> On Aug 23, 2018, at 12:37 AM, Geert Janssens  
> 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
gnucash-devel@gnucash.org
https://lists.gnucash.org/mailman/listinfo/gnucash-devel

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

[John Ralls]

> On Aug 23, 2018, at 12:45 AM, Geert Janssens  
> wrote:
> 
> Op dinsdag 21 augustus 2018 21:24:25 CEST schreef John Ralls:
>>> On Aug 21, 2018, at 11:50 AM, Geert Janssens 
>>> 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
gnucash-devel@gnucash.org
https://lists.gnucash.org/mailman/listinfo/gnucash-devel

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

[John Ralls]

> On Aug 23, 2018, at 6:37 AM, Geert Janssens  
> wrote:
> 
> Op donderdag 23 augustus 2018 15:08:54 CEST schreef Derek Atkins:
>> Geert Janssens  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/ 
 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
gnucash-devel@gnucash.org
https://lists.gnucash.org/mailman/listinfo/gnucash-devel

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

[Geert Janssens]

Op donderdag 23 augustus 2018 15:08:54 CEST schreef Derek Atkins:
> Geert Janssens  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
gnucash-devel@gnucash.org
https://lists.gnucash.org/mailman/listinfo/gnucash-devel

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

[Derek Atkins]

Geert Janssens  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

-- 
   Derek Atkins, SB '93 MIT EE, SM '95 MIT Media Laboratory
   Member, MIT Student Information Processing Board  (SIPB)
   URL: http://web.mit.edu/warlord/PP-ASEL-IA N1NWH
   warl...@mit.eduPGP key available
___
gnucash-devel mailing list
gnucash-devel@gnucash.org
https://lists.gnucash.org/mailman/listinfo/gnucash-devel

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

[Geert Janssens]

Op dinsdag 21 augustus 2018 21:36:58 CEST schreef John Ralls:
> > On Aug 21, 2018, at 11:50 AM, Geert Janssens 
> > 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.

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
gnucash-devel@gnucash.org
https://lists.gnucash.org/mailman/listinfo/gnucash-devel

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

[Geert Janssens]

Op dinsdag 21 augustus 2018 21:24:25 CEST schreef John Ralls:
> > On Aug 21, 2018, at 11:50 AM, Geert Janssens 
> > 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.

Geert


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

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

[Geert Janssens]

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.

Regards,

Geert


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

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

[John Ralls]

> On Aug 21, 2018, at 11:50 AM, Geert Janssens  
> wrote:
> 
> 
> I believe the gnome project is using Mallard (http://projectmallard.org/). 

That depends. The Gnome applications that have help at all use mallard (which 
is a Docbook dialect) on which they apply yelp-tools and itstool to create 
documentation. The libraries use gtk-doc to extract specially formatted 
comments and convert that to a form of Docbook to feed to yelp tools and 
itstool. In general those documents are published only on the web. The 
application docs are very simple, no more than a few pages.

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

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.

Regards,
John Ralls

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

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

[John Ralls]

Adrien,

If you mean https://help.gnome.org , those docs are 
built using Yelp tools, see 
https://gitlab.gnome.org/GNOME?utf8=%E2%9C%93=yelp 
. Most of that 
documentation seems pretty cursory, even for largish apps like Gnome Web (aka 
Epiphany).

Not all “Gnome” projects are included there. The GIMP and Inkscape (though I 
guess since Inkscape doesn’t keep their repo on gitlab.gnome.org 
 they’re no more a Gnome app than we are), for 
example, both maintain their own documentation (in DocBook) and doc build 
scripts.

Gimp’s docs are similar to ours if one doesn’t use viewdoc: They stand apart; 
there are links to the previous and next pages, there’s a “home” link back to 
the TOC, but nothing tying it to the main website.

Inkscape doesn’t really have a comprehensive manual. There’s a man page (not on 
their website) and 9 single-page tutorials (written in DocBook) that are 
displayed as regular website content pages with no extra links beyond the site 
menubar across the top.

No doubt that viewdoc.phtml could be improved. As Geert noted it’s pretty 
basic, just 144 lines of php. If someone fluent in modern php and css would 
like to overhaul and modernize the website we’d welcome it, but I think the 
core team’s time is better spent on GnuCash itself.

Regards,
John Ralls

> On Aug 21, 2018, at 8:49 AM, Adrien Monteleone 
>  wrote:
> 
> Thanks for the background info Geert,
> 
> I recall a discussion some time ago about the tools and methods used to 
> generate the documentation, and I think based on that thread and the info 
> you’ve just provided that the solution lies in a new method entirely. (frames 
> aren’t really the best option as you noted)
> 
> I’ll try to dig up that old thread, but is there a list of ’needs’ of the 
> developers to use when evaluating methods?
> 
> The only thing I can find recently is that the intended approach was to 
> create an “O’Reilly” style book, (just a goal or hard and fast requirement?) 
> and I recall there needed to be a means to generate PDF, .mobi, and .epub 
> versions.
> 
> As for the current method, I see docbook has something called docbook-xslt 
> which is a stylesheet approach to layout and other visuals. It seems geared 
> more toward print than web, but I supposed it could be used for such. This 
> strikes me though as trying to find a means to keep using the proverbial 
> hammer rather than a more appropriate tool. Though, I do see Gnome is still 
> using Docbook and their user help is well integrated into their website as 
> individual web pages, (breadcrumbs and all) and not anything resembling a 
> printed page.
> 
> Regards,
> Adrien
> 
>> On Aug 21, 2018, at 2:46 AM, Geert Janssens  
>> wrote:
>> 
>> Op dinsdag 21 augustus 2018 02:44:59 CEST schreef Adrien Monteleone:
>>> David C,
>>> 
>>> So for clarification this is the first link you posted about:
 https://www.gnucash.org/docs/v3/C/gnucash-guide/txns-register-oview.html#t
 xns-regstyle1
>>> Notice this is in the folder /docs/v3/C/gnucash-guide/
>>> 
>>> But the link on the Documentation page and the link you included (both in 
>> that first post and in the last one) that said how you got there was this:
 https://www.gnucash.org/viewdoc.phtml?rev=3=C=help
>>> 
>>> So yes, that IS version 3 (listed here as ‘rev=3’) but that’s not the same
>>> link as above. (though it might be the exact same content, I didn’t check)
>>> 
>>> I can’t find any way, other than typing it in directly, to get to the
>>> /docs/v3/C/ directory wherein lies the /gnucash-guide/ and /gnucash-help/
>>> folders and contents. All of the links on the documentation page seem to
>>> point instead to the /viewdoc.phtml which never changes the URL as you
>>> navigate the document. (my guess is the viewdoc.phtml template is serving
>>> the pages physically located in /docs/v3/C/, we just can’t see the real
>>> URL)
>> 
>> The viewdoc.phtml page is a first and imperfect attempt to integrate the 
>> documentation in the website.
>> 
>> It ensures that while presenting the documentation the main website's 
>> navigation menus and style are still visible. Before that page existed 
>> clicking on a documentation link would suddenly remove all website 
>> decorations 
>> and just show you the documentation on a plain white page with no option to 
>> navigate to other parts of the main website.
>> 
>> viewdoc.phtml is just a wrapper that opens the actual documentation in a 
>> separate frame. If you ask your browser to open that frame in its own window 
>> you'll see the direct links David posted here.
>> 
>> The use of a frame is old-fashioned and has indeed many limitations. It was 
>> the only option at the time that could be implemented with reasonable effort.
>> 
>> Of course it would be much nicer to have bread crumbs and clear links for 
>> each 
>> page. And a documentation navigation menu integrated in the 

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

[John Ralls]

> On Aug 21, 2018, at 11:50 AM, Geert Janssens  
> 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.

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.

Regards,
John Ralls


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

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

[Geert Janssens]

Op dinsdag 21 augustus 2018 17:49:57 CEST schreef Adrien Monteleone:
> Thanks for the background info Geert,
> 
> I recall a discussion some time ago about the tools and methods used to
> generate the documentation, and I think based on that thread and the info
> you’ve just provided that the solution lies in a new method entirely.
> (frames aren’t really the best option as you noted)
> 


> I’ll try to dig up that old thread,
This comes up every now an then...

There was a long thread in 2015 suggesting asciidoc, latex or libreoffice as 
alternative formats:
https://lists.gnucash.org/pipermail/gnucash-devel/2015-August/038976.html
https://lists.gnucash.org/pipermail/gnucash-devel/2015-September/038984.html

This was preceded by another thread on this topic:
https://lists.gnucash.org/pipermail/gnucash-devel/2015-August/038952.html

And that thread referred back to a similar thread in 2013:
http://lists.gnucash.org/pipermail/gnucash-devel/2013-December/036626.html

And in May 2017 there was another foray into 'new documentation tooling' land 
as part of this thread:
https://lists.gnucash.org/pipermail/gnucash-devel/2017-May/040600.html

I'm sure there will be more of them.

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

> The only thing I can find recently is that the intended approach was to
> create an “O’Reilly” style book, (just a goal or hard and fast
> requirement?) and I recall there needed to be a means to generate PDF,
> .mobi, and .epub versions.
> 
> As for the current method, I see docbook has something called docbook-xslt
> which is a stylesheet approach to layout and other visuals. It seems geared
> more toward print than web, but I supposed it could be used for such. This
> strikes me though as trying to find a means to keep using the proverbial
> hammer rather than a more appropriate tool. Though, I do see Gnome is still
> using Docbook and their user help is well integrated into their website as
> individual web pages, (breadcrumbs and all) and not anything resembling a
> printed page.

I believe the gnome project is using Mallard (http://projectmallard.org/). 
Aside from that they also expect there writers to work with git.

Geert


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

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

[Adrien Monteleone]

> On Aug 21, 2018, at 7:12 AM, David T.  wrote:
> 
> David,
> 
> I haven’t advocated for renaming the documents. I changed a couple of 
> headings on the main wiki page.
> 
> There are two documents, 
> 
> 1) the Help Manual
> and
> 2) the Tutorial and Concepts Guide
> 
> as outlined at gnucash.org.
> 
> One might refer to them respectively as the “Help” and the “Guide”. There is 
> no "Help Guide.”
> 
> As for Adrien’s question regarding what goes where, there was a discussion a 
> few years back on precisely this issue—i.e., on what exactly is meant by 
> "Help Manual” and “Tutorial and Concepts Guide” and what, therefore should go 
> into each document. I can’t put my hands on that thread right now, but the 
> upshot was that the Help was seen by most as the place that identifies “this 
> button does this function” kinds of instruction, while the Guide is intended 
> to contain “if I am trying to accomplish goal X, here is how to do that.” 
> These categories are admittedly fuzzy around the edges. I admit that I am 
> more of a “how do I do X” kind of person, and so have worked most on 
> upgrading the Guide.

I think John addressed this very well in the other thread about Wiki main page 
editing. His description of the two documents should probably now be put on the 
website as well.

> 
> Finally, the website was redesigned  years ago, and the 
> current generic addressing scheme was implemented at that time. I commented 
> on it at the time, but we never came to any resolutions. I suspect some kind 
> of batter and breadcrumb solution (along with a flash frying in a nice deep 
> fryer) might help with navigation. When I am directing someone to a specific 
> page in the documentation, I right-click the link to the page in question, 
> and copy  the link. That provides the full URL.

Thanks for the tip. And that is probably how David C copied that direct link. 
The picture is much clearer now.

Regards,
Adrien


> 
> David
> 
>> On Aug 20, 2018, at 7:52 PM, David Carlson  
>> wrote:
>> 
>> I too am confused now.  First, I think David > > stated in the other documentation thread that the
>> document names need to be clarified, and that may be part of why I am
>> confused.  I think that the short names seem to be Guide and Tutorial,
>> which, if they were used consistently, would work for me.  I may be wrong
>> about the names.
>> 
>> Second, I think that there may be an alias issue, and I am not sure where I
>> am sometimes because of that. In my last foray into online documentation I
>> was specifically trying to get to the current stable (Release 3) version of
>> the documentation, and when I repeat my itinerary as I tried to describe in
>> previous posts, I do end up in pages identified as ../v3/..  So I am
>> puzzled that Adrien does not seem to get to the same place, or how some of
>> my previous attempts to document the trip do not seem to be leading to
>> pages identified as ../v3/..
>> 
>> Third, I think that document title and chapter numbers do not appear on
>> every page in each form of the documentation, and that has not helped me to
>> keep track of where I am.
>> 
>> Fourth, the label on the link in the tip just below figure 4.3 of the help
>> manual is named Tutorial and Concepts Guide and it does seem to point to
>> the Tutorial ../v3/..section 4.2, so it seems correct for the current
>> document structure.
>> 
>> I am not trying to rant, just document my confusion and agreement that
>> simplification would be helpful.
>> 
>> David C
>> 
>> On Mon, Aug 20, 2018 at 4:30 PM, Adrien Monteleone <
>> adrien.montele...@lusfiber.net> wrote:
>> 
>>> Hmm.. Not sure how I missed that recently. (I’ve read it before)
>>> 
>>> But then if it’s there, I wonder why so many questions still? Perhaps the
>>> organization or presentation isn’t very discoverable? User laziness?
>>> 
>>> Also, I still don’t think after several years that I’m clear on the
>>> difference between the Help Manual and the Tutorial & Concepts Guide. I get
>>> what their names imply and I understand the explanation on the website, but
>>> here is a case of info that I would expect to find in the other document.
>>> This is info about the GUI itself, not ‘how to use’ GnuCash to accomplish
>>> an accounting task. (which the name “Tutorial & Concepts Guide” implies and
>>> even the website itself defines as the document’s function)
>>> 
>>> Should this be relocated to the Help Manual?
>>> 
>>> Regards,
>>> Adrien
>>> 
 On Aug 20, 2018, at 3:44 PM, D  wrote:
 
 And you will find said documentation in the Guide at 2.3.3.
 
 David
 
 On August 20, 2018, at 2:32 PM, Derek Atkins  wrote:
 
 
 On Mon, August 20, 2018 2:20 pm, Adrien Monteleone wrote:
> Of course, that all makes sense.
> 
> The other improvements, specifically how to resize columns, particularly
> the Description column I think should be documented. There are enough
> questions on the list about it to address the 

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

[Adrien Monteleone]

Thanks for the background info Geert,

I recall a discussion some time ago about the tools and methods used to 
generate the documentation, and I think based on that thread and the info 
you’ve just provided that the solution lies in a new method entirely. (frames 
aren’t really the best option as you noted)

I’ll try to dig up that old thread, but is there a list of ’needs’ of the 
developers to use when evaluating methods?

The only thing I can find recently is that the intended approach was to create 
an “O’Reilly” style book, (just a goal or hard and fast requirement?) and I 
recall there needed to be a means to generate PDF, .mobi, and .epub versions.

As for the current method, I see docbook has something called docbook-xslt 
which is a stylesheet approach to layout and other visuals. It seems geared 
more toward print than web, but I supposed it could be used for such. This 
strikes me though as trying to find a means to keep using the proverbial hammer 
rather than a more appropriate tool. Though, I do see Gnome is still using 
Docbook and their user help is well integrated into their website as individual 
web pages, (breadcrumbs and all) and not anything resembling a printed page.

Regards,
Adrien

> On Aug 21, 2018, at 2:46 AM, Geert Janssens  
> wrote:
> 
> Op dinsdag 21 augustus 2018 02:44:59 CEST schreef Adrien Monteleone:
>> David C,
>> 
>> So for clarification this is the first link you posted about:
>>> https://www.gnucash.org/docs/v3/C/gnucash-guide/txns-register-oview.html#t
>>> xns-regstyle1
>> Notice this is in the folder /docs/v3/C/gnucash-guide/
>> 
>> But the link on the Documentation page and the link you included (both in 
> that first post and in the last one) that said how you got there was this:
>>> https://www.gnucash.org/viewdoc.phtml?rev=3=C=help
>> 
>> So yes, that IS version 3 (listed here as ‘rev=3’) but that’s not the same
>> link as above. (though it might be the exact same content, I didn’t check)
>> 
>> I can’t find any way, other than typing it in directly, to get to the
>> /docs/v3/C/ directory wherein lies the /gnucash-guide/ and /gnucash-help/
>> folders and contents. All of the links on the documentation page seem to
>> point instead to the /viewdoc.phtml which never changes the URL as you
>> navigate the document. (my guess is the viewdoc.phtml template is serving
>> the pages physically located in /docs/v3/C/, we just can’t see the real
>> URL)
> 
> The viewdoc.phtml page is a first and imperfect attempt to integrate the 
> documentation in the website.
> 
> It ensures that while presenting the documentation the main website's 
> navigation menus and style are still visible. Before that page existed 
> clicking on a documentation link would suddenly remove all website 
> decorations 
> and just show you the documentation on a plain white page with no option to 
> navigate to other parts of the main website.
> 
> viewdoc.phtml is just a wrapper that opens the actual documentation in a 
> separate frame. If you ask your browser to open that frame in its own window 
> you'll see the direct links David posted here.
> 
> The use of a frame is old-fashioned and has indeed many limitations. It was 
> the only option at the time that could be implemented with reasonable effort.
> 
> Of course it would be much nicer to have bread crumbs and clear links for 
> each 
> page. And a documentation navigation menu integrated in the website's main 
> decorations.
> 
> However from how I understand this would mean to create a specialized docbook 
> style used exclusively to generate the documentation section of our website. 
> I 
> believe the way we currently generate the gnucash html documentation is not 
> fit for integration. Writing such a specialized docbook style is possible, 
> but 
> I never found time to dig in.
> 
> Regards,
> 
> Geert


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

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

[David T. via gnucash-devel]

David,

I haven’t advocated for renaming the documents. I changed a couple of headings 
on the main wiki page.

There are two documents, 

1) the Help Manual
and
2) the Tutorial and Concepts Guide

as outlined at gnucash.org .

One might refer to them respectively as the “Help” and the “Guide”. There is no 
"Help Guide.”

As for Adrien’s question regarding what goes where, there was a discussion a 
few years back on precisely this issue—i.e., on what exactly is meant by "Help 
Manual” and “Tutorial and Concepts Guide” and what, therefore should go into 
each document. I can’t put my hands on that thread right now, but the upshot 
was that the Help was seen by most as the place that identifies “this button 
does this function” kinds of instruction, while the Guide is intended to 
contain “if I am trying to accomplish goal X, here is how to do that.” These 
categories are admittedly fuzzy around the edges. I admit that I am more of a 
“how do I do X” kind of person, and so have worked most on upgrading the Guide.

Finally, the website was redesigned  years ago, and the current 
generic addressing scheme was implemented at that time. I commented on it at 
the time, but we never came to any resolutions. I suspect some kind of batter 
and breadcrumb solution (along with a flash frying in a nice deep fryer) might 
help with navigation. When I am directing someone to a specific page in the 
documentation, I right-click the link to the page in question, and copy  the 
link. That provides the full URL.

David

> On Aug 20, 2018, at 7:52 PM, David Carlson  
> wrote:
> 
> I too am confused now.  First, I think David  > stated in the other documentation thread that the
> document names need to be clarified, and that may be part of why I am
> confused.  I think that the short names seem to be Guide and Tutorial,
> which, if they were used consistently, would work for me.  I may be wrong
> about the names.
> 
> Second, I think that there may be an alias issue, and I am not sure where I
> am sometimes because of that. In my last foray into online documentation I
> was specifically trying to get to the current stable (Release 3) version of
> the documentation, and when I repeat my itinerary as I tried to describe in
> previous posts, I do end up in pages identified as ../v3/..  So I am
> puzzled that Adrien does not seem to get to the same place, or how some of
> my previous attempts to document the trip do not seem to be leading to
> pages identified as ../v3/..
> 
> Third, I think that document title and chapter numbers do not appear on
> every page in each form of the documentation, and that has not helped me to
> keep track of where I am.
> 
> Fourth, the label on the link in the tip just below figure 4.3 of the help
> manual is named Tutorial and Concepts Guide and it does seem to point to
> the Tutorial ../v3/..section 4.2, so it seems correct for the current
> document structure.
> 
> I am not trying to rant, just document my confusion and agreement that
> simplification would be helpful.
> 
> David C
> 
> On Mon, Aug 20, 2018 at 4:30 PM, Adrien Monteleone <
> adrien.montele...@lusfiber.net> wrote:
> 
>> Hmm.. Not sure how I missed that recently. (I’ve read it before)
>> 
>> But then if it’s there, I wonder why so many questions still? Perhaps the
>> organization or presentation isn’t very discoverable? User laziness?
>> 
>> Also, I still don’t think after several years that I’m clear on the
>> difference between the Help Manual and the Tutorial & Concepts Guide. I get
>> what their names imply and I understand the explanation on the website, but
>> here is a case of info that I would expect to find in the other document.
>> This is info about the GUI itself, not ‘how to use’ GnuCash to accomplish
>> an accounting task. (which the name “Tutorial & Concepts Guide” implies and
>> even the website itself defines as the document’s function)
>> 
>> Should this be relocated to the Help Manual?
>> 
>> Regards,
>> Adrien
>> 
>>> On Aug 20, 2018, at 3:44 PM, D  wrote:
>>> 
>>> And you will find said documentation in the Guide at 2.3.3.
>>> 
>>> David
>>> 
>>> On August 20, 2018, at 2:32 PM, Derek Atkins  wrote:
>>> 
>>> 
>>> On Mon, August 20, 2018 2:20 pm, Adrien Monteleone wrote:
 Of course, that all makes sense.
 
 The other improvements, specifically how to resize columns, particularly
 the Description column I think should be documented. There are enough
 questions on the list about it to address the topic.
>>> 
>>> Absolutely!
>>> 
 Regards,
 Adrien
>>> 
 Please remember to CC this list on all your replies.
 You can do this by using Reply-To-List or Reply-All.
>>> 
>>> -derek
>>> --
>>>  Derek Atkins 617-623-3745
>>>  de...@ihtfp.com www.ihtfp.com
>>>  Computer and Internet Security Consultant
>> 
>> ___
>> gnucash-devel mailing list
>> gnucash-devel@gnucash.org
>> 

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

[Geert Janssens]

Op dinsdag 21 augustus 2018 02:44:59 CEST schreef Adrien Monteleone:
> David C,
> 
> So for clarification this is the first link you posted about:
> > https://www.gnucash.org/docs/v3/C/gnucash-guide/txns-register-oview.html#t
> > xns-regstyle1
> Notice this is in the folder /docs/v3/C/gnucash-guide/
> 
> But the link on the Documentation page and the link you included (both in 
that first post and in the last one) that said how you got there was this:
> > https://www.gnucash.org/viewdoc.phtml?rev=3=C=help
> 
> So yes, that IS version 3 (listed here as ‘rev=3’) but that’s not the same
> link as above. (though it might be the exact same content, I didn’t check)
> 
> I can’t find any way, other than typing it in directly, to get to the
> /docs/v3/C/ directory wherein lies the /gnucash-guide/ and /gnucash-help/
> folders and contents. All of the links on the documentation page seem to
> point instead to the /viewdoc.phtml which never changes the URL as you
> navigate the document. (my guess is the viewdoc.phtml template is serving
> the pages physically located in /docs/v3/C/, we just can’t see the real
> URL)

The viewdoc.phtml page is a first and imperfect attempt to integrate the 
documentation in the website.

It ensures that while presenting the documentation the main website's 
navigation menus and style are still visible. Before that page existed 
clicking on a documentation link would suddenly remove all website decorations 
and just show you the documentation on a plain white page with no option to 
navigate to other parts of the main website.

viewdoc.phtml is just a wrapper that opens the actual documentation in a 
separate frame. If you ask your browser to open that frame in its own window 
you'll see the direct links David posted here.

The use of a frame is old-fashioned and has indeed many limitations. It was 
the only option at the time that could be implemented with reasonable effort.

Of course it would be much nicer to have bread crumbs and clear links for each 
page. And a documentation navigation menu integrated in the website's main 
decorations.

However from how I understand this would mean to create a specialized docbook 
style used exclusively to generate the documentation section of our website. I 
believe the way we currently generate the gnucash html documentation is not 
fit for integration. Writing such a specialized docbook style is possible, but 
I never found time to dig in.

Regards,

Geert



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

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

[David Carlson]

I will try inline editing, even though it is very difficult in Gmail


David C

On Mon, Aug 20, 2018 at 7:44 PM, Adrien Monteleone <
adrien.montele...@lusfiber.net> wrote:

> David C,
>
> So for clarification this is the first link you posted about:
>
> > https://www.gnucash.org/docs/v3/C/gnucash-guide/txns-
> register-oview.html#txns-regstyle1
>
> Notice this is in the folder /docs/v3/C/gnucash-guide/
>
> But the link on the Documentation page and the link you included (both in
> that first post and in the last one) that said how you got there was this:
>
> > https://www.gnucash.org/viewdoc.phtml?rev=3=C=help


When I follow that link the url is not the same as when I go down the tree
through the online help.   That must be why I thought there were aliases
involved and why it appeared to me that you were not seeing the same
material.  It appears that the modifiers doc=help and doc=guide in phtml
point indirectly to the proper directories.  Thus, the correct (at this
time) short names are help and guide.  I would find it easier if they were
changed to something more intuitive such as help and tutorial.  I will
leave that part of the discussion to the other thread.



>
> So yes, that IS version 3 (listed here as ‘rev=3’) but that’s not the same
> link as above. (though it might be the exact same content, I didn’t check)
>
> I can’t find any way, other than typing it in directly, to get to the
> /docs/v3/C/ directory wherein lies the /gnucash-guide/ and /gnucash-help/
> folders and contents. All of the links on the documentation page seem to
> point instead to the /viewdoc.phtml which never changes the URL as you
> navigate the document. (my guess is the viewdoc.phtml template is serving
> the pages physically located in /docs/v3/C/, we just can’t see the real URL)
>
> 
>
> And now after I backed up a few directories from the first link above, I
> see regardless, *I* was in the wrong place. I didn’t see a ‘4.3' because I
> was looking at the section numbers which are roman numerals, not the
> chapter numbers. Section IV in the Guide are for the Appendices which are
> organized by letters. The only notation I saw then for 4.3 was in the Help
> Manual, which is where my confusion came from. (but that really is where I
> think this info should be - see my previous comment)
>
> And sure enough there is https://www.gnucash.org/docs/v3/C/gnucash-help/
> which I would have expected to see.
>
> So, we can put aside the naming of the folder since that’s correct. But
> what certainly would be helpful is if the page itself indicated which
> document you were viewing. That bug is still there.
>

Yes, I agree.



> Regards,
> Adrien
>
>
> > On Aug 20, 2018, at 6:52 PM, David Carlson 
> wrote:
> >
> > I too am confused now.  First, I think David 
> stated in the other documentation thread that the document names need to be
> clarified, and that may be part of why I am confused.  I think that the
> short names seem to be Guide and Tutorial, which, if they were used
> consistently, would work for me.  I may be wrong about the names.
> >
> > Second, I think that there may be an alias issue, and I am not sure
> where I am sometimes because of that. In my last foray into online
> documentation I was specifically trying to get to the current stable
> (Release 3) version of the documentation, and when I repeat my itinerary as
> I tried to describe in previous posts, I do end up in pages identified as
> ../v3/..  So I am puzzled that Adrien does not seem to get to the same
> place, or how some of my previous attempts to document the trip do not seem
> to be leading to pages identified as ../v3/..
> >
> > Third, I think that document title and chapter numbers do not appear on
> every page in each form of the documentation, and that has not helped me to
> keep track of where I am.
> >
> > Fourth, the label on the link in the tip just below figure 4.3 of the
> help manual is named Tutorial and Concepts Guide and it does seem to point
> to the Tutorial ../v3/..section 4.2, so it seems correct for the current
> document structure.
> >
> > I am not trying to rant, just document my confusion and agreement that
> simplification would be helpful.
> >
> > David C
> >
> > On Mon, Aug 20, 2018 at 4:30 PM, Adrien Monteleone <
> adrien.montele...@lusfiber.net> wrote:
> > Hmm.. Not sure how I missed that recently. (I’ve read it before)
> >
> > But then if it’s there, I wonder why so many questions still? Perhaps
> the organization or presentation isn’t very discoverable? User laziness?
> >
> > Also, I still don’t think after several years that I’m clear on the
> difference between the Help Manual and the Tutorial & Concepts Guide. I get
> what their names imply and I understand the explanation on the website, but
> here is a case of info that I would expect to find in the other document.
> This is info about the GUI itself, not ‘how to use’ GnuCash to accomplish
> an accounting task. (which the name “Tutorial & Concepts Guide” 

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

[Adrien Monteleone]

David C,

So for clarification this is the first link you posted about:

> https://www.gnucash.org/docs/v3/C/gnucash-guide/txns-register-oview.html#txns-regstyle1

Notice this is in the folder /docs/v3/C/gnucash-guide/

But the link on the Documentation page and the link you included (both in that 
first post and in the last one) that said how you got there was this:

> https://www.gnucash.org/viewdoc.phtml?rev=3=C=help

So yes, that IS version 3 (listed here as ‘rev=3’) but that’s not the same link 
as above. (though it might be the exact same content, I didn’t check)

I can’t find any way, other than typing it in directly, to get to the 
/docs/v3/C/ directory wherein lies the /gnucash-guide/ and /gnucash-help/ 
folders and contents. All of the links on the documentation page seem to point 
instead to the /viewdoc.phtml which never changes the URL as you navigate the 
document. (my guess is the viewdoc.phtml template is serving the pages 
physically located in /docs/v3/C/, we just can’t see the real URL)



And now after I backed up a few directories from the first link above, I see 
regardless, *I* was in the wrong place. I didn’t see a ‘4.3' because I was 
looking at the section numbers which are roman numerals, not the chapter 
numbers. Section IV in the Guide are for the Appendices which are organized by 
letters. The only notation I saw then for 4.3 was in the Help Manual, which is 
where my confusion came from. (but that really is where I think this info 
should be - see my previous comment)

And sure enough there is https://www.gnucash.org/docs/v3/C/gnucash-help/ which 
I would have expected to see.

So, we can put aside the naming of the folder since that’s correct. But what 
certainly would be helpful is if the page itself indicated which document you 
were viewing. That bug is still there.

Regards,
Adrien


> On Aug 20, 2018, at 6:52 PM, David Carlson  
> wrote:
> 
> I too am confused now.  First, I think David  stated in 
> the other documentation thread that the document names need to be clarified, 
> and that may be part of why I am confused.  I think that the short names seem 
> to be Guide and Tutorial, which, if they were used consistently, would work 
> for me.  I may be wrong about the names.
> 
> Second, I think that there may be an alias issue, and I am not sure where I 
> am sometimes because of that. In my last foray into online documentation I 
> was specifically trying to get to the current stable (Release 3) version of 
> the documentation, and when I repeat my itinerary as I tried to describe in 
> previous posts, I do end up in pages identified as ../v3/..  So I am puzzled 
> that Adrien does not seem to get to the same place, or how some of my 
> previous attempts to document the trip do not seem to be leading to pages 
> identified as ../v3/..
> 
> Third, I think that document title and chapter numbers do not appear on every 
> page in each form of the documentation, and that has not helped me to keep 
> track of where I am.
> 
> Fourth, the label on the link in the tip just below figure 4.3 of the help 
> manual is named Tutorial and Concepts Guide and it does seem to point to the 
> Tutorial ../v3/..section 4.2, so it seems correct for the current document 
> structure.
> 
> I am not trying to rant, just document my confusion and agreement that 
> simplification would be helpful.  
> 
> David C
> 
> On Mon, Aug 20, 2018 at 4:30 PM, Adrien Monteleone 
>  wrote:
> Hmm.. Not sure how I missed that recently. (I’ve read it before)
> 
> But then if it’s there, I wonder why so many questions still? Perhaps the 
> organization or presentation isn’t very discoverable? User laziness?
> 
> Also, I still don’t think after several years that I’m clear on the 
> difference between the Help Manual and the Tutorial & Concepts Guide. I get 
> what their names imply and I understand the explanation on the website, but 
> here is a case of info that I would expect to find in the other document. 
> This is info about the GUI itself, not ‘how to use’ GnuCash to accomplish an 
> accounting task. (which the name “Tutorial & Concepts Guide” implies and even 
> the website itself defines as the document’s function)
> 
> Should this be relocated to the Help Manual?
> 
> Regards,
> Adrien
> 
> > On Aug 20, 2018, at 3:44 PM, D  wrote:
> > 
> > And you will find said documentation in the Guide at 2.3.3.
> > 
> > David
> > 
> > On August 20, 2018, at 2:32 PM, Derek Atkins  wrote:
> > 
> > 
> > On Mon, August 20, 2018 2:20 pm, Adrien Monteleone wrote:
> >> Of course, that all makes sense.
> >> 
> >> The other improvements, specifically how to resize columns, particularly
> >> the Description column I think should be documented. There are enough
> >> questions on the list about it to address the topic.
> > 
> > Absolutely!
> > 
> >> Regards,
> >> Adrien
> > 
> >> Please remember to CC this list on all your replies.
> >> You can do this by using Reply-To-List or Reply-All.
> > 
> > -derek
> > 

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

[David Carlson]

I too am confused now.  First, I think David > stated in the other documentation thread that the
document names need to be clarified, and that may be part of why I am
confused.  I think that the short names seem to be Guide and Tutorial,
which, if they were used consistently, would work for me.  I may be wrong
about the names.

Second, I think that there may be an alias issue, and I am not sure where I
am sometimes because of that. In my last foray into online documentation I
was specifically trying to get to the current stable (Release 3) version of
the documentation, and when I repeat my itinerary as I tried to describe in
previous posts, I do end up in pages identified as ../v3/..  So I am
puzzled that Adrien does not seem to get to the same place, or how some of
my previous attempts to document the trip do not seem to be leading to
pages identified as ../v3/..

Third, I think that document title and chapter numbers do not appear on
every page in each form of the documentation, and that has not helped me to
keep track of where I am.

Fourth, the label on the link in the tip just below figure 4.3 of the help
manual is named Tutorial and Concepts Guide and it does seem to point to
the Tutorial ../v3/..section 4.2, so it seems correct for the current
document structure.

I am not trying to rant, just document my confusion and agreement that
simplification would be helpful.

David C

On Mon, Aug 20, 2018 at 4:30 PM, Adrien Monteleone <
adrien.montele...@lusfiber.net> wrote:

> Hmm.. Not sure how I missed that recently. (I’ve read it before)
>
> But then if it’s there, I wonder why so many questions still? Perhaps the
> organization or presentation isn’t very discoverable? User laziness?
>
> Also, I still don’t think after several years that I’m clear on the
> difference between the Help Manual and the Tutorial & Concepts Guide. I get
> what their names imply and I understand the explanation on the website, but
> here is a case of info that I would expect to find in the other document.
> This is info about the GUI itself, not ‘how to use’ GnuCash to accomplish
> an accounting task. (which the name “Tutorial & Concepts Guide” implies and
> even the website itself defines as the document’s function)
>
> Should this be relocated to the Help Manual?
>
> Regards,
> Adrien
>
> > On Aug 20, 2018, at 3:44 PM, D  wrote:
> >
> > And you will find said documentation in the Guide at 2.3.3.
> >
> > David
> >
> > On August 20, 2018, at 2:32 PM, Derek Atkins  wrote:
> >
> >
> > On Mon, August 20, 2018 2:20 pm, Adrien Monteleone wrote:
> >> Of course, that all makes sense.
> >>
> >> The other improvements, specifically how to resize columns, particularly
> >> the Description column I think should be documented. There are enough
> >> questions on the list about it to address the topic.
> >
> > Absolutely!
> >
> >> Regards,
> >> Adrien
> >
> >> Please remember to CC this list on all your replies.
> >> You can do this by using Reply-To-List or Reply-All.
> >
> > -derek
> > --
> >   Derek Atkins 617-623-3745
> >   de...@ihtfp.com www.ihtfp.com
> >   Computer and Internet Security Consultant
>
> ___
> gnucash-devel mailing list
> gnucash-devel@gnucash.org
> https://lists.gnucash.org/mailman/listinfo/gnucash-devel
>
___
gnucash-devel mailing list
gnucash-devel@gnucash.org
https://lists.gnucash.org/mailman/listinfo/gnucash-devel

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

[Adrien Monteleone]

Hmm.. Not sure how I missed that recently. (I’ve read it before)

But then if it’s there, I wonder why so many questions still? Perhaps the 
organization or presentation isn’t very discoverable? User laziness?

Also, I still don’t think after several years that I’m clear on the difference 
between the Help Manual and the Tutorial & Concepts Guide. I get what their 
names imply and I understand the explanation on the website, but here is a case 
of info that I would expect to find in the other document. This is info about 
the GUI itself, not ‘how to use’ GnuCash to accomplish an accounting task. 
(which the name “Tutorial & Concepts Guide” implies and even the website itself 
defines as the document’s function)

Should this be relocated to the Help Manual?

Regards,
Adrien

> On Aug 20, 2018, at 3:44 PM, D  wrote:
> 
> And you will find said documentation in the Guide at 2.3.3.
> 
> David
> 
> On August 20, 2018, at 2:32 PM, Derek Atkins  wrote:
> 
> 
> On Mon, August 20, 2018 2:20 pm, Adrien Monteleone wrote:
>> Of course, that all makes sense.
>> 
>> The other improvements, specifically how to resize columns, particularly
>> the Description column I think should be documented. There are enough
>> questions on the list about it to address the topic.
> 
> Absolutely!
> 
>> Regards,
>> Adrien
> 
>> Please remember to CC this list on all your replies.
>> You can do this by using Reply-To-List or Reply-All.
> 
> -derek
> -- 
>   Derek Atkins 617-623-3745
>   de...@ihtfp.com www.ihtfp.com
>   Computer and Internet Security Consultant

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

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

[Adrien Monteleone]

Strange, I followed that path and I still only get /viewdoc links. I can’t seem 
to hit the /docs/v3 section of the site. (notice your link is also to the 
/viewdoc URL, not /docs/v3)

Anyway, as for Gmail, it’s there, you have to click in the reply box to start 
your reply for it to appear. (I tested that on both the older and the newer 
version of Gmail before my last reply) You can also use the drop down in the 
upper right of the message with the same arrow which will move your keyboard 
focus to the reply box. (same as clicking in it directly)

Regards,
Adrien

> On Aug 20, 2018, at 1:54 PM, David Carlson  
> wrote:
> 
> OK.
> 
> For my complete itinerary, I started at the GnuCash home page 
> https://www.gnucash.org/.
> Clicked on Downloads > Documentation in the left column 
> https://www.gnucash.org/docs.phtml
> from there I scrolled down the right to
> GnuCash v3 (current stable release)
> 
> then I selected Download Stable Help Manual English Browse Documentation 
> Online "
>   https://www.gnucash.org/viewdoc.phtml?rev=3=C=help
> 
> There is where I found the incorrectly titled and badly worded link.
> 
> Also, I am still using the aout to be replaced Gmail version on the internet, 
> and I do nt see what you described by the reply arrow, although my memory 
> tells me that it used to be there.
> 
> David C
> 
> 
> On Mon, Aug 20, 2018 at 1:06 PM, Adrien Monteleone 
>  wrote:
> David,
> 
> The confusion as to which document you were in I think is that the link text 
> says ‘gnucash-guide’. There are also several references scattered on the 
> website/wiki that refer to the ‘Help Guide’ though it appears the 
> Documentation page calls it the ‘Help Manual’. That folder name I should 
> think is a bug.
> 
> How did you get to that /docs/v3 link? I can’t find any path to it from the 
> website. The links I find are all /viewdoc links which don’t tell me where I 
> am. (at least not in the URL, just as you discovered - which brings up 
> another navigation bug, the pages have no indication of what document you are 
> viewing)
> 
> Also, I’ve changed the subject for you, and moved it to gnucash-devel. (I 
> thought about doing the same on the last reply, I suppose the thread is 
> officially hijacked now)
> 
> In Gmail, in the reply box, there is a down arrow next to the reply 
> left-pointing arrow. (just to the left of the recipient(s)) Click it for a 
> context menu and use “Edit Subject”
> 
> Regards,
> Adrien
> 
> 
> 
> > On Aug 20, 2018, at 12:04 PM, David Carlson  
> > wrote:
> > 
> > Adrien,
> > 
> > Thank you for your research and detailed response. 
> > I fully agree with your conclusions.
> > 
> > 
> > I got the reference to section 4.2 directly from 
> > https://www.gnucash.org/docs/v3/C/gnucash-guide/txns-register-oview.html#txns-regstyle1
> >  which I arrived at when I followed the link called " Tutorial and Concepts 
> > Guide, Choosing a Register Style). " in 
> > https://www.gnucash.org/viewdoc.phtml?doc=help.  Naturally, I thought I was 
> > in the Tutorial...
> > 
> > David C
> > 
> > On Mon, Aug 20, 2018 at 11:45 AM, Adrien Monteleone 
> >  wrote:
> > I’ve never seen any documentation on it. I only confirmed it’s there after 
> > I read Derek’s comment and expanded the column myself to see it.
> > 
> > I just did a search of the GnuCash site, wiki and html docs and I don’t see 
> > anything on the column, other than a pair of IRC logs from 2009 where 
> > someone asked what it was for, and a couple of hits (appears duplicated) 
> > documenting commits from 2017-09-4. I didn’t read the commit itself, but it 
> > was summarized by Robert Fewell as “Add a heading for the Rate column.”
> > 
> > Concerning where to put the info, I’m not sure the Tutorial is the right 
> > place. (there is no 4.2, for example)
> > 
> > However, the help guide has 4.3.5 List of Transactions which documents the 
> > column headings. I think if that section were more detailed with 
> > screenshots, lots of questions could be answered or even avoided.
> > 
> > Some things to add here:
> > 
> > The ability to resize columns and an explanation of how the Description 
> > column is special and how resizing works.
> > 
> > An explanation with screenshots of the different types of registers showing 
> > the respective columns. (unless they are all the same, save terminology 
> > choices, then you’d only need one screenshot)
> > 
> > An explanation of the formal vs. non-formal labels for each account type. 
> > (a full listing of what the non-formal labels are for each type)
> > 
> > Screenshots depicting each of the modes: single-line, double-line, 
> > transaction journal.
> > 
> > An explanation of what each cell in the transaction is for. (many don’t 
> > know the utilit(ies) of NUM or Action for example.) Not everything is 
> > self-evident. Perhaps here include a link to a special wiki page or to 
> > Using GnuCash where the different ’tricks’ for using those and other fields 
> > to accomplish user 

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

[David Carlson]

OK.

For my complete itinerary, I started at the GnuCash home page
https://www.gnucash.org/.
Clicked on Downloads > Documentation in the left column
https://www.gnucash.org/docs.phtml
from there I scrolled down the right to GnuCash v3 (current stable release)
then I selected Download Stable Help Manual English Browse Documentation
Online "
  https://www.gnucash.org/viewdoc.phtml?rev=3=C=help

There is where I found the incorrectly titled and badly worded link.

Also, I am still using the aout to be replaced Gmail version on the
internet, and I do nt see what you described by the reply arrow, although
my memory tells me that it used to be there.

David C


On Mon, Aug 20, 2018 at 1:06 PM, Adrien Monteleone <
adrien.montele...@lusfiber.net> wrote:

> David,
>
> The confusion as to which document you were in I think is that the link
> text says ‘gnucash-guide’. There are also several references scattered on
> the website/wiki that refer to the ‘Help Guide’ though it appears the
> Documentation page calls it the ‘Help Manual’. That folder name I should
> think is a bug.
>
> How did you get to that /docs/v3 link? I can’t find any path to it from
> the website. The links I find are all /viewdoc links which don’t tell me
> where I am. (at least not in the URL, just as you discovered - which brings
> up another navigation bug, the pages have no indication of what document
> you are viewing)
>
> Also, I’ve changed the subject for you, and moved it to gnucash-devel. (I
> thought about doing the same on the last reply, I suppose the thread is
> officially hijacked now)
>
> In Gmail, in the reply box, there is a down arrow next to the reply
> left-pointing arrow. (just to the left of the recipient(s)) Click it for a
> context menu and use “Edit Subject”
>
> Regards,
> Adrien
>
>
>
> > On Aug 20, 2018, at 12:04 PM, David Carlson 
> wrote:
> >
> > Adrien,
> >
> > Thank you for your research and detailed response. 
> > I fully agree with your conclusions.
> >
> >
> > I got the reference to section 4.2 directly from
> https://www.gnucash.org/docs/v3/C/gnucash-guide/txns-
> register-oview.html#txns-regstyle1 which I arrived at when I followed the
> link called " Tutorial and Concepts Guide, Choosing a Register Style). " in
> https://www.gnucash.org/viewdoc.phtml?doc=help.  Naturally, I thought I
> was in the Tutorial...
> >
> > David C
> >
> > On Mon, Aug 20, 2018 at 11:45 AM, Adrien Monteleone <
> adrien.montele...@lusfiber.net> wrote:
> > I’ve never seen any documentation on it. I only confirmed it’s there
> after I read Derek’s comment and expanded the column myself to see it.
> >
> > I just did a search of the GnuCash site, wiki and html docs and I don’t
> see anything on the column, other than a pair of IRC logs from 2009 where
> someone asked what it was for, and a couple of hits (appears duplicated)
> documenting commits from 2017-09-4. I didn’t read the commit itself, but it
> was summarized by Robert Fewell as “Add a heading for the Rate column.”
> >
> > Concerning where to put the info, I’m not sure the Tutorial is the right
> place. (there is no 4.2, for example)
> >
> > However, the help guide has 4.3.5 List of Transactions which documents
> the column headings. I think if that section were more detailed with
> screenshots, lots of questions could be answered or even avoided.
> >
> > Some things to add here:
> >
> > The ability to resize columns and an explanation of how the Description
> column is special and how resizing works.
> >
> > An explanation with screenshots of the different types of registers
> showing the respective columns. (unless they are all the same, save
> terminology choices, then you’d only need one screenshot)
> >
> > An explanation of the formal vs. non-formal labels for each account
> type. (a full listing of what the non-formal labels are for each type)
> >
> > Screenshots depicting each of the modes: single-line, double-line,
> transaction journal.
> >
> > An explanation of what each cell in the transaction is for. (many don’t
> know the utilit(ies) of NUM or Action for example.) Not everything is
> self-evident. Perhaps here include a link to a special wiki page or to
> Using GnuCash where the different ’tricks’ for using those and other fields
> to accomplish user specific goals are (or should be) documented.
> >
> > I would be happy to get set up for editing and start on this unless you
> already planned on running with it.
> >
> > Finally, “Tutorial & Concepts Guide” is a bit winded. Could it simply be
> “Tutorial” or “Using GnuCash”? (and then incorporate any ‘official’ methods
> from that wiki page into the document, with a link to that page for the
> non-standard methods)
> >
> > Regards,
> > Adrien
> >
> > > On Aug 20, 2018, at 10:57 AM, David Carlson <
> david.carlson@gmail.com> wrote:
> > >
> > > I just tried to find reference to the rate field in the Tutorial and I
> found nothing.
> > >
> > > I think it should probably be mentioned in chapter 4 section 4.2.
> That 

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

[Adrien Monteleone]

I just filed: https://bugs.gnucash.org/show_bug.cgi?id=796823

On the title issue as that’s a basic website usability bug.

I’ll wait for someone else to chime in on the case of the gnucash-guide folder.

Regards,
Adrien

> On Aug 20, 2018, at 1:06 PM, Adrien Monteleone 
>  wrote:
> 
> David,
> 
> The confusion as to which document you were in I think is that the link text 
> says ‘gnucash-guide’. There are also several references scattered on the 
> website/wiki that refer to the ‘Help Guide’ though it appears the 
> Documentation page calls it the ‘Help Manual’. That folder name I should 
> think is a bug.
> 
> How did you get to that /docs/v3 link? I can’t find any path to it from the 
> website. The links I find are all /viewdoc links which don’t tell me where I 
> am. (at least not in the URL, just as you discovered - which brings up 
> another navigation bug, the pages have no indication of what document you are 
> viewing)
> 
> Also, I’ve changed the subject for you, and moved it to gnucash-devel. (I 
> thought about doing the same on the last reply, I suppose the thread is 
> officially hijacked now)
> 
> In Gmail, in the reply box, there is a down arrow next to the reply 
> left-pointing arrow. (just to the left of the recipient(s)) Click it for a 
> context menu and use “Edit Subject”
> 
> Regards,
> Adrien
> 
> 
> 
>> On Aug 20, 2018, at 12:04 PM, David Carlson  
>> wrote:
>> 
>> Adrien,
>> 
>> Thank you for your research and detailed response. 
>> I fully agree with your conclusions.
>> 
>> 
>> I got the reference to section 4.2 directly from 
>> https://www.gnucash.org/docs/v3/C/gnucash-guide/txns-register-oview.html#txns-regstyle1
>>  which I arrived at when I followed the link called " Tutorial and Concepts 
>> Guide, Choosing a Register Style). " in 
>> https://www.gnucash.org/viewdoc.phtml?doc=help.  Naturally, I thought I was 
>> in the Tutorial...
>> 
>> David C
>> 
>> On Mon, Aug 20, 2018 at 11:45 AM, Adrien Monteleone 
>>  wrote:
>> I’ve never seen any documentation on it. I only confirmed it’s there after I 
>> read Derek’s comment and expanded the column myself to see it.
>> 
>> I just did a search of the GnuCash site, wiki and html docs and I don’t see 
>> anything on the column, other than a pair of IRC logs from 2009 where 
>> someone asked what it was for, and a couple of hits (appears duplicated) 
>> documenting commits from 2017-09-4. I didn’t read the commit itself, but it 
>> was summarized by Robert Fewell as “Add a heading for the Rate column.”
>> 
>> Concerning where to put the info, I’m not sure the Tutorial is the right 
>> place. (there is no 4.2, for example)
>> 
>> However, the help guide has 4.3.5 List of Transactions which documents the 
>> column headings. I think if that section were more detailed with 
>> screenshots, lots of questions could be answered or even avoided.
>> 
>> Some things to add here:
>> 
>> The ability to resize columns and an explanation of how the Description 
>> column is special and how resizing works.
>> 
>> An explanation with screenshots of the different types of registers showing 
>> the respective columns. (unless they are all the same, save terminology 
>> choices, then you’d only need one screenshot)
>> 
>> An explanation of the formal vs. non-formal labels for each account type. (a 
>> full listing of what the non-formal labels are for each type)
>> 
>> Screenshots depicting each of the modes: single-line, double-line, 
>> transaction journal.
>> 
>> An explanation of what each cell in the transaction is for. (many don’t know 
>> the utilit(ies) of NUM or Action for example.) Not everything is 
>> self-evident. Perhaps here include a link to a special wiki page or to Using 
>> GnuCash where the different ’tricks’ for using those and other fields to 
>> accomplish user specific goals are (or should be) documented.
>> 
>> I would be happy to get set up for editing and start on this unless you 
>> already planned on running with it.
>> 
>> Finally, “Tutorial & Concepts Guide” is a bit winded. Could it simply be 
>> “Tutorial” or “Using GnuCash”? (and then incorporate any ‘official’ methods 
>> from that wiki page into the document, with a link to that page for the 
>> non-standard methods)
>> 
>> Regards,
>> Adrien
>> 
>>> On Aug 20, 2018, at 10:57 AM, David Carlson  
>>> wrote:
>>> 
>>> I just tried to find reference to the rate field in the Tutorial and I 
>>> found nothing.
>>> 
>>> I think it should probably be mentioned in chapter 4 section 4.2.  That 
>>> section even fails to explain single line vs two line view or dragging 
>>> around field widths, so it has a long way to go before it could describe 
>>> the presence of the rate field and how to access it.
>>> 
>>> Is this information posted elsewhere? 
>>> 
>>> David C 
>>> 
>>> On Mon, Aug 20, 2018, 9:44 AM Adrien Monteleone 
>>>  wrote:
>>> It’s still there as of 3.2.
>>> 
>>> Regards,
>>> Adrien
>>> 
 On Aug 20, 2018, at 9:17 AM, Derek Atkins  wrote:
 
 John 

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

[Adrien Monteleone]

David,

The confusion as to which document you were in I think is that the link text 
says ‘gnucash-guide’. There are also several references scattered on the 
website/wiki that refer to the ‘Help Guide’ though it appears the Documentation 
page calls it the ‘Help Manual’. That folder name I should think is a bug.

How did you get to that /docs/v3 link? I can’t find any path to it from the 
website. The links I find are all /viewdoc links which don’t tell me where I 
am. (at least not in the URL, just as you discovered - which brings up another 
navigation bug, the pages have no indication of what document you are viewing)

Also, I’ve changed the subject for you, and moved it to gnucash-devel. (I 
thought about doing the same on the last reply, I suppose the thread is 
officially hijacked now)

In Gmail, in the reply box, there is a down arrow next to the reply 
left-pointing arrow. (just to the left of the recipient(s)) Click it for a 
context menu and use “Edit Subject”

Regards,
Adrien



> On Aug 20, 2018, at 12:04 PM, David Carlson  
> wrote:
> 
> Adrien,
> 
> Thank you for your research and detailed response. 
> I fully agree with your conclusions.
> 
> 
> I got the reference to section 4.2 directly from 
> https://www.gnucash.org/docs/v3/C/gnucash-guide/txns-register-oview.html#txns-regstyle1
>  which I arrived at when I followed the link called " Tutorial and Concepts 
> Guide, Choosing a Register Style). " in 
> https://www.gnucash.org/viewdoc.phtml?doc=help.  Naturally, I thought I was 
> in the Tutorial...
> 
> David C
> 
> On Mon, Aug 20, 2018 at 11:45 AM, Adrien Monteleone 
>  wrote:
> I’ve never seen any documentation on it. I only confirmed it’s there after I 
> read Derek’s comment and expanded the column myself to see it.
> 
> I just did a search of the GnuCash site, wiki and html docs and I don’t see 
> anything on the column, other than a pair of IRC logs from 2009 where someone 
> asked what it was for, and a couple of hits (appears duplicated) documenting 
> commits from 2017-09-4. I didn’t read the commit itself, but it was 
> summarized by Robert Fewell as “Add a heading for the Rate column.”
> 
> Concerning where to put the info, I’m not sure the Tutorial is the right 
> place. (there is no 4.2, for example)
> 
> However, the help guide has 4.3.5 List of Transactions which documents the 
> column headings. I think if that section were more detailed with screenshots, 
> lots of questions could be answered or even avoided.
> 
> Some things to add here:
> 
> The ability to resize columns and an explanation of how the Description 
> column is special and how resizing works.
> 
> An explanation with screenshots of the different types of registers showing 
> the respective columns. (unless they are all the same, save terminology 
> choices, then you’d only need one screenshot)
> 
> An explanation of the formal vs. non-formal labels for each account type. (a 
> full listing of what the non-formal labels are for each type)
> 
> Screenshots depicting each of the modes: single-line, double-line, 
> transaction journal.
> 
> An explanation of what each cell in the transaction is for. (many don’t know 
> the utilit(ies) of NUM or Action for example.) Not everything is 
> self-evident. Perhaps here include a link to a special wiki page or to Using 
> GnuCash where the different ’tricks’ for using those and other fields to 
> accomplish user specific goals are (or should be) documented.
> 
> I would be happy to get set up for editing and start on this unless you 
> already planned on running with it.
> 
> Finally, “Tutorial & Concepts Guide” is a bit winded. Could it simply be 
> “Tutorial” or “Using GnuCash”? (and then incorporate any ‘official’ methods 
> from that wiki page into the document, with a link to that page for the 
> non-standard methods)
> 
> Regards,
> Adrien
> 
> > On Aug 20, 2018, at 10:57 AM, David Carlson  
> > wrote:
> > 
> > I just tried to find reference to the rate field in the Tutorial and I 
> > found nothing.
> > 
> > I think it should probably be mentioned in chapter 4 section 4.2.  That 
> > section even fails to explain single line vs two line view or dragging 
> > around field widths, so it has a long way to go before it could describe 
> > the presence of the rate field and how to access it.
> > 
> > Is this information posted elsewhere? 
> > 
> > David C 
> > 
> > On Mon, Aug 20, 2018, 9:44 AM Adrien Monteleone 
> >  wrote:
> > It’s still there as of 3.2.
> > 
> > Regards,
> > Adrien
> > 
> > > On Aug 20, 2018, at 9:17 AM, Derek Atkins  wrote:
> > > 
> > > John Ralls  writes:
> > > 
> > >> Graham,
> > >> 
> > >> "Transfer" is short for "Transfer Account" and is the field where the
> > >> "other" account--other than the one in the current register--is
> > >> set. It's often called the "account" field in casual use.
> > >> 
> > >> I think GTI made a translation error, the "rate" field is probably
> > >> "price" on a stock/mutual fund register, which has two more