[GNC-dev] Documentation update problems

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

[GNC-dev] Documentation update problems

GnuCash - Dev mailing list
Hello,

If I am working on updating the documentation, it must be time for me to bang my head against some command line hiccup! <looks at wrist> Yup! Right on time.

Following my handy-dandy git cheat sheet, I’ve pulled from github.com/gnucash/gnucash-docs <http://github.com/gnucash/gnucash-docs> and pushed to github.com/sunfish62/gnucash-docs <http://github.com/sunfish62/gnucash-docs>. I then entered all my edits to ch_basics.xml and saved.

Next, I went to the wiki (https://wiki.gnucash.org/wiki/Documentation_Update_Instructions#Validate_Your_Changes <https://wiki.gnucash.org/wiki/Documentation_Update_Instructions#Validate_Your_Changes>) and found the instructions to “make check” the guide. So, in Terminal, I cd to my build directory for the guide (/Volumes/Media/Development/Gnucash/gnucash-docs/build/guide) and issue “make clean”

This is what I get:

cd .. && /Applications/Xcode.app/Contents/Developer/usr/bin/make  am--refresh
CDPATH="${ZSH_VERSION+.}:" && cd .. && /bin/sh /Volumes/Media/Development/Gnucash/gnucash-docs/missing aclocal-1.15
 cd .. && /bin/sh /Volumes/Media/Development/Gnucash/gnucash-docs/missing automake-1.15 --gnu
configure.ac:6: error: required file './config.guess' not found
configure.ac:6:   'automake --add-missing' can install 'config.guess'
configure.ac:6: error: required file './config.sub' not found
configure.ac:6:   'automake --add-missing' can install 'config.sub'
xmldocs.make:54: warning: shell ls ${srcdir}/${figdir}/*.png: non-POSIX variable name
xmldocs.make:54: (probably a GNU make extension)
guide/C/Makefile.am:42:   'xmldocs.make' included from here
xmldocs.make:85: warning: shell ls ${srcdir}/${figdir}/*.png: non-POSIX variable name
xmldocs.make:85: (probably a GNU make extension)
guide/C/Makefile.am:42:   'xmldocs.make' included from here
xmldocs.make:54: warning: shell ls ${srcdir}/${figdir}/*.png: non-POSIX variable name
xmldocs.make:54: (probably a GNU make extension)
guide/de/Makefile.am:40:   'xmldocs.make' included from here
xmldocs.make:85: warning: shell ls ${srcdir}/${figdir}/*.png: non-POSIX variable name
xmldocs.make:85: (probably a GNU make extension)
guide/de/Makefile.am:40:   'xmldocs.make' included from here
xmldocs.make:54: warning: shell ls ${srcdir}/${figdir}/*.png: non-POSIX variable name
xmldocs.make:54: (probably a GNU make extension)
guide/it/Makefile.am:11:   'xmldocs.make' included from here
xmldocs.make:85: warning: shell ls ${srcdir}/${figdir}/*.png: non-POSIX variable name
xmldocs.make:85: (probably a GNU make extension)
guide/it/Makefile.am:11:   'xmldocs.make' included from here
xmldocs.make:54: warning: shell ls ${srcdir}/${figdir}/*.png: non-POSIX variable name
xmldocs.make:54: (probably a GNU make extension)
guide/ja/Makefile.am:37:   'xmldocs.make' included from here
xmldocs.make:85: warning: shell ls ${srcdir}/${figdir}/*.png: non-POSIX variable name
xmldocs.make:85: (probably a GNU make extension)
guide/ja/Makefile.am:37:   'xmldocs.make' included from here
xmldocs.make:54: warning: shell ls ${srcdir}/${figdir}/*.png: non-POSIX variable name
xmldocs.make:54: (probably a GNU make extension)
guide/pt/Makefile.am:43:   'xmldocs.make' included from here
xmldocs.make:85: warning: shell ls ${srcdir}/${figdir}/*.png: non-POSIX variable name
xmldocs.make:85: (probably a GNU make extension)
guide/pt/Makefile.am:43:   'xmldocs.make' included from here
xmldocs.make:54: warning: shell ls ${srcdir}/${figdir}/*.png: non-POSIX variable name
xmldocs.make:54: (probably a GNU make extension)
guide/ru/Makefile.am:37:   'xmldocs.make' included from here
xmldocs.make:85: warning: shell ls ${srcdir}/${figdir}/*.png: non-POSIX variable name
xmldocs.make:85: (probably a GNU make extension)
guide/ru/Makefile.am:37:   'xmldocs.make' included from here
xmldocs.make:54: warning: shell ls ${srcdir}/${figdir}/*.png: non-POSIX variable name
xmldocs.make:54: (probably a GNU make extension)
help/C/Makefile.am:33:   'xmldocs.make' included from here
xmldocs.make:85: warning: shell ls ${srcdir}/${figdir}/*.png: non-POSIX variable name
xmldocs.make:85: (probably a GNU make extension)
help/C/Makefile.am:33:   'xmldocs.make' included from here
xmldocs.make:54: warning: shell ls ${srcdir}/${figdir}/*.png: non-POSIX variable name
xmldocs.make:54: (probably a GNU make extension)
help/de/Makefile.am:20:   'xmldocs.make' included from here
xmldocs.make:85: warning: shell ls ${srcdir}/${figdir}/*.png: non-POSIX variable name
xmldocs.make:85: (probably a GNU make extension)
help/de/Makefile.am:20:   'xmldocs.make' included from here
xmldocs.make:54: warning: shell ls ${srcdir}/${figdir}/*.png: non-POSIX variable name
xmldocs.make:54: (probably a GNU make extension)
help/it/Makefile.am:11:   'xmldocs.make' included from here
xmldocs.make:85: warning: shell ls ${srcdir}/${figdir}/*.png: non-POSIX variable name
xmldocs.make:85: (probably a GNU make extension)
help/it/Makefile.am:11:   'xmldocs.make' included from here
xmldocs.make:54: warning: shell ls ${srcdir}/${figdir}/*.png: non-POSIX variable name
xmldocs.make:54: (probably a GNU make extension)
help/pt/Makefile.am:28:   'xmldocs.make' included from here
xmldocs.make:85: warning: shell ls ${srcdir}/${figdir}/*.png: non-POSIX variable name
xmldocs.make:85: (probably a GNU make extension)
help/pt/Makefile.am:28:   'xmldocs.make' included from here
make[1]: *** [../Makefile.in] Error 1
make: *** [../../aclocal.m4] Error 2

I’m not sure why there’s a “missing” in the initial command, and I don’t know where config.guess is supposed to be—and I won’t even try to guess.

I would love to have some guidance.

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

Re: [GNC-dev] Documentation update problems

GnuCash - Dev mailing list
For what it’s worth, I was able to dig out the old xmllint/xsltproc commands and test and view my edits.

I’d still love to know how I’ve f**ked up my development environment so that the currently-sanctioned approach (make|make clean|make install|make hay while the sun shines) doesn’t work.

Perhaps this is another instance of not trying to teach old dogs new tricks.

David


> On Aug 16, 2018, at 11:41 PM, David T. via gnucash-devel <[hidden email]> wrote:
>
> Hello,
>
> If I am working on updating the documentation, it must be time for me to bang my head against some command line hiccup! <looks at wrist> Yup! Right on time.
>
> Following my handy-dandy git cheat sheet, I’ve pulled from github.com/gnucash/gnucash-docs <http://github.com/gnucash/gnucash-docs> and pushed to github.com/sunfish62/gnucash-docs <http://github.com/sunfish62/gnucash-docs>. I then entered all my edits to ch_basics.xml and saved.
>
> Next, I went to the wiki (https://wiki.gnucash.org/wiki/Documentation_Update_Instructions#Validate_Your_Changes <https://wiki.gnucash.org/wiki/Documentation_Update_Instructions#Validate_Your_Changes>) and found the instructions to “make check” the guide. So, in Terminal, I cd to my build directory for the guide (/Volumes/Media/Development/Gnucash/gnucash-docs/build/guide) and issue “make clean”
>
> This is what I get:
>
> cd .. && /Applications/Xcode.app/Contents/Developer/usr/bin/make  am--refresh
> CDPATH="${ZSH_VERSION+.}:" && cd .. && /bin/sh /Volumes/Media/Development/Gnucash/gnucash-docs/missing aclocal-1.15
> cd .. && /bin/sh /Volumes/Media/Development/Gnucash/gnucash-docs/missing automake-1.15 --gnu
> configure.ac:6: error: required file './config.guess' not found
> configure.ac:6:   'automake --add-missing' can install 'config.guess'
> configure.ac:6: error: required file './config.sub' not found
> configure.ac:6:   'automake --add-missing' can install 'config.sub'
> xmldocs.make:54: warning: shell ls ${srcdir}/${figdir}/*.png: non-POSIX variable name
> xmldocs.make:54: (probably a GNU make extension)
> guide/C/Makefile.am:42:   'xmldocs.make' included from here
> xmldocs.make:85: warning: shell ls ${srcdir}/${figdir}/*.png: non-POSIX variable name
> xmldocs.make:85: (probably a GNU make extension)
> guide/C/Makefile.am:42:   'xmldocs.make' included from here
> xmldocs.make:54: warning: shell ls ${srcdir}/${figdir}/*.png: non-POSIX variable name
> xmldocs.make:54: (probably a GNU make extension)
> guide/de/Makefile.am:40:   'xmldocs.make' included from here
> xmldocs.make:85: warning: shell ls ${srcdir}/${figdir}/*.png: non-POSIX variable name
> xmldocs.make:85: (probably a GNU make extension)
> guide/de/Makefile.am:40:   'xmldocs.make' included from here
> xmldocs.make:54: warning: shell ls ${srcdir}/${figdir}/*.png: non-POSIX variable name
> xmldocs.make:54: (probably a GNU make extension)
> guide/it/Makefile.am:11:   'xmldocs.make' included from here
> xmldocs.make:85: warning: shell ls ${srcdir}/${figdir}/*.png: non-POSIX variable name
> xmldocs.make:85: (probably a GNU make extension)
> guide/it/Makefile.am:11:   'xmldocs.make' included from here
> xmldocs.make:54: warning: shell ls ${srcdir}/${figdir}/*.png: non-POSIX variable name
> xmldocs.make:54: (probably a GNU make extension)
> guide/ja/Makefile.am:37:   'xmldocs.make' included from here
> xmldocs.make:85: warning: shell ls ${srcdir}/${figdir}/*.png: non-POSIX variable name
> xmldocs.make:85: (probably a GNU make extension)
> guide/ja/Makefile.am:37:   'xmldocs.make' included from here
> xmldocs.make:54: warning: shell ls ${srcdir}/${figdir}/*.png: non-POSIX variable name
> xmldocs.make:54: (probably a GNU make extension)
> guide/pt/Makefile.am:43:   'xmldocs.make' included from here
> xmldocs.make:85: warning: shell ls ${srcdir}/${figdir}/*.png: non-POSIX variable name
> xmldocs.make:85: (probably a GNU make extension)
> guide/pt/Makefile.am:43:   'xmldocs.make' included from here
> xmldocs.make:54: warning: shell ls ${srcdir}/${figdir}/*.png: non-POSIX variable name
> xmldocs.make:54: (probably a GNU make extension)
> guide/ru/Makefile.am:37:   'xmldocs.make' included from here
> xmldocs.make:85: warning: shell ls ${srcdir}/${figdir}/*.png: non-POSIX variable name
> xmldocs.make:85: (probably a GNU make extension)
> guide/ru/Makefile.am:37:   'xmldocs.make' included from here
> xmldocs.make:54: warning: shell ls ${srcdir}/${figdir}/*.png: non-POSIX variable name
> xmldocs.make:54: (probably a GNU make extension)
> help/C/Makefile.am:33:   'xmldocs.make' included from here
> xmldocs.make:85: warning: shell ls ${srcdir}/${figdir}/*.png: non-POSIX variable name
> xmldocs.make:85: (probably a GNU make extension)
> help/C/Makefile.am:33:   'xmldocs.make' included from here
> xmldocs.make:54: warning: shell ls ${srcdir}/${figdir}/*.png: non-POSIX variable name
> xmldocs.make:54: (probably a GNU make extension)
> help/de/Makefile.am:20:   'xmldocs.make' included from here
> xmldocs.make:85: warning: shell ls ${srcdir}/${figdir}/*.png: non-POSIX variable name
> xmldocs.make:85: (probably a GNU make extension)
> help/de/Makefile.am:20:   'xmldocs.make' included from here
> xmldocs.make:54: warning: shell ls ${srcdir}/${figdir}/*.png: non-POSIX variable name
> xmldocs.make:54: (probably a GNU make extension)
> help/it/Makefile.am:11:   'xmldocs.make' included from here
> xmldocs.make:85: warning: shell ls ${srcdir}/${figdir}/*.png: non-POSIX variable name
> xmldocs.make:85: (probably a GNU make extension)
> help/it/Makefile.am:11:   'xmldocs.make' included from here
> xmldocs.make:54: warning: shell ls ${srcdir}/${figdir}/*.png: non-POSIX variable name
> xmldocs.make:54: (probably a GNU make extension)
> help/pt/Makefile.am:28:   'xmldocs.make' included from here
> xmldocs.make:85: warning: shell ls ${srcdir}/${figdir}/*.png: non-POSIX variable name
> xmldocs.make:85: (probably a GNU make extension)
> help/pt/Makefile.am:28:   'xmldocs.make' included from here
> make[1]: *** [../Makefile.in] Error 1
> make: *** [../../aclocal.m4] Error 2
>
> I’m not sure why there’s a “missing” in the initial command, and I don’t know where config.guess is supposed to be—and I won’t even try to guess.
>
> I would love to have some guidance.
>
> David T.
> _______________________________________________
> gnucash-devel mailing list
> [hidden email]
> https://lists.gnucash.org/mailman/listinfo/gnucash-devel

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

Re: [GNC-dev] Documentation update problems

Geert Janssens-4
In reply to this post by GnuCash - Dev mailing list
Op vrijdag 17 augustus 2018 08:41:05 CEST schreef David T. via gnucash-devel:

> Hello,
>
> If I am working on updating the documentation, it must be time for me to
> bang my head against some command line hiccup! <looks at wrist> Yup! Right
> on time.
>
> Following my handy-dandy git cheat sheet, I’ve pulled from
> github.com/gnucash/gnucash-docs <http://github.com/gnucash/gnucash-docs>
> and pushed to github.com/sunfish62/gnucash-docs
> <http://github.com/sunfish62/gnucash-docs>. I then entered all my edits to
> ch_basics.xml and saved.
>
> Next, I went to the wiki
> (https://wiki.gnucash.org/wiki/Documentation_Update_Instructions#Validate_Y
> our_Changes
> <https://wiki.gnucash.org/wiki/Documentation_Update_Instructions#Validate_Y
> our_Changes>) and found the instructions to “make check” the guide. So, in
> Terminal, I cd to my build directory for the guide
> (/Volumes/Media/Development/Gnucash/gnucash-docs/build/guide) and issue
> “make clean”
>
> This is what I get:
>
> cd .. && /Applications/Xcode.app/Contents/Developer/usr/bin/make
> am--refresh CDPATH="${ZSH_VERSION+.}:" && cd .. && /bin/sh
> /Volumes/Media/Development/Gnucash/gnucash-docs/missing aclocal-1.15 cd ..
> && /bin/sh /Volumes/Media/Development/Gnucash/gnucash-docs/missing
> automake-1.15 --gnu configure.ac:6: error: required file './config.guess'
> not found
> configure.ac:6:   'automake --add-missing' can install 'config.guess'
> configure.ac:6: error: required file './config.sub' not found
> configure.ac:6:   'automake --add-missing' can install 'config.sub'
> xmldocs.make:54: warning: shell ls ${srcdir}/${figdir}/*.png: non-POSIX
> variable name xmldocs.make:54: (probably a GNU make extension)
> guide/C/Makefile.am:42:   'xmldocs.make' included from here
> xmldocs.make:85: warning: shell ls ${srcdir}/${figdir}/*.png: non-POSIX
> variable name xmldocs.make:85: (probably a GNU make extension)
> guide/C/Makefile.am:42:   'xmldocs.make' included from here
> xmldocs.make:54: warning: shell ls ${srcdir}/${figdir}/*.png: non-POSIX
> variable name xmldocs.make:54: (probably a GNU make extension)
> guide/de/Makefile.am:40:   'xmldocs.make' included from here
> xmldocs.make:85: warning: shell ls ${srcdir}/${figdir}/*.png: non-POSIX
> variable name xmldocs.make:85: (probably a GNU make extension)
> guide/de/Makefile.am:40:   'xmldocs.make' included from here
> xmldocs.make:54: warning: shell ls ${srcdir}/${figdir}/*.png: non-POSIX
> variable name xmldocs.make:54: (probably a GNU make extension)
> guide/it/Makefile.am:11:   'xmldocs.make' included from here
> xmldocs.make:85: warning: shell ls ${srcdir}/${figdir}/*.png: non-POSIX
> variable name xmldocs.make:85: (probably a GNU make extension)
> guide/it/Makefile.am:11:   'xmldocs.make' included from here
> xmldocs.make:54: warning: shell ls ${srcdir}/${figdir}/*.png: non-POSIX
> variable name xmldocs.make:54: (probably a GNU make extension)
> guide/ja/Makefile.am:37:   'xmldocs.make' included from here
> xmldocs.make:85: warning: shell ls ${srcdir}/${figdir}/*.png: non-POSIX
> variable name xmldocs.make:85: (probably a GNU make extension)
> guide/ja/Makefile.am:37:   'xmldocs.make' included from here
> xmldocs.make:54: warning: shell ls ${srcdir}/${figdir}/*.png: non-POSIX
> variable name xmldocs.make:54: (probably a GNU make extension)
> guide/pt/Makefile.am:43:   'xmldocs.make' included from here
> xmldocs.make:85: warning: shell ls ${srcdir}/${figdir}/*.png: non-POSIX
> variable name xmldocs.make:85: (probably a GNU make extension)
> guide/pt/Makefile.am:43:   'xmldocs.make' included from here
> xmldocs.make:54: warning: shell ls ${srcdir}/${figdir}/*.png: non-POSIX
> variable name xmldocs.make:54: (probably a GNU make extension)
> guide/ru/Makefile.am:37:   'xmldocs.make' included from here
> xmldocs.make:85: warning: shell ls ${srcdir}/${figdir}/*.png: non-POSIX
> variable name xmldocs.make:85: (probably a GNU make extension)
> guide/ru/Makefile.am:37:   'xmldocs.make' included from here
> xmldocs.make:54: warning: shell ls ${srcdir}/${figdir}/*.png: non-POSIX
> variable name xmldocs.make:54: (probably a GNU make extension)
> help/C/Makefile.am:33:   'xmldocs.make' included from here
> xmldocs.make:85: warning: shell ls ${srcdir}/${figdir}/*.png: non-POSIX
> variable name xmldocs.make:85: (probably a GNU make extension)
> help/C/Makefile.am:33:   'xmldocs.make' included from here
> xmldocs.make:54: warning: shell ls ${srcdir}/${figdir}/*.png: non-POSIX
> variable name xmldocs.make:54: (probably a GNU make extension)
> help/de/Makefile.am:20:   'xmldocs.make' included from here
> xmldocs.make:85: warning: shell ls ${srcdir}/${figdir}/*.png: non-POSIX
> variable name xmldocs.make:85: (probably a GNU make extension)
> help/de/Makefile.am:20:   'xmldocs.make' included from here
> xmldocs.make:54: warning: shell ls ${srcdir}/${figdir}/*.png: non-POSIX
> variable name xmldocs.make:54: (probably a GNU make extension)
> help/it/Makefile.am:11:   'xmldocs.make' included from here
> xmldocs.make:85: warning: shell ls ${srcdir}/${figdir}/*.png: non-POSIX
> variable name xmldocs.make:85: (probably a GNU make extension)
> help/it/Makefile.am:11:   'xmldocs.make' included from here
> xmldocs.make:54: warning: shell ls ${srcdir}/${figdir}/*.png: non-POSIX
> variable name xmldocs.make:54: (probably a GNU make extension)
> help/pt/Makefile.am:28:   'xmldocs.make' included from here
> xmldocs.make:85: warning: shell ls ${srcdir}/${figdir}/*.png: non-POSIX
> variable name xmldocs.make:85: (probably a GNU make extension)
> help/pt/Makefile.am:28:   'xmldocs.make' included from here
> make[1]: *** [../Makefile.in] Error 1
> make: *** [../../aclocal.m4] Error 2
>
> I’m not sure why there’s a “missing” in the initial command, and I don’t
> know where config.guess is supposed to be—and I won’t even try to guess.
>
> I would love to have some guidance.
>

I went to look at the wiki page and unfortunately it's incomplete. You get
this error because a few essential commands have been omitted.

I have added a section that should fill the gap. Can you proofread this:
https://wiki.gnucash.org/wiki/
Documentation_Update_Instructions#Prepare_The_Build_Directory
And report back any issues you experience ?

It's written these steps are usually done early in in the set up process, but
you can still run them right now and then retry the validation.

Geert


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

Re: [GNC-dev] Documentation update problems

Frank H. Ellenberger-3
Am 17.08.2018 um 09:18 schrieb Geert Janssens:
> Op vrijdag 17 augustus 2018 08:41:05 CEST schreef David T. via gnucash-devel:
:

>> I’m not sure why there’s a “missing” in the initial command, and I don’t
>> know where config.guess is supposed to be—and I won’t even try to guess.
>>
>> I would love to have some guidance.
>>
>
> I went to look at the wiki page and unfortunately it's incomplete. You get
> this error because a few essential commands have been omitted.
>
> I have added a section that should fill the gap. Can you proofread this:
> https://wiki.gnucash.org/wiki/
> Documentation_Update_Instructions#Prepare_The_Build_Directory
> And report back any issues you experience ?
>
> It's written these steps are usually done early in in the set up process, but
> you can still run them right now and then retry the validation.
>
> Geert

Yeah, the missing section got lost in
https://wiki.gnucash.org/wiki/index.php?title=Documentation_Update_Instructions&type=revision&diff=13215&oldid=12785

OTOH it was a major improvement of the readability.

Regards
Frank

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

Re: [GNC-dev] Documentation update problems

GnuCash - Dev mailing list
Frank, Geert,

I am finally following up on this thread, and I’d like to note that the information that Frank says “got lost,” and which Geert has re-entered on this page were actually moved to a different page (https://wiki.gnucash.org/wiki/Initializing_Documentation_Build_Environment <https://wiki.gnucash.org/wiki/Initializing_Documentation_Build_Environment>) and the reference to this information was moved up to Section 2. Setting Up Your System.

Here we have an example of how duplicative information ends up in our ecosystem!

For the future, we should change the Documentation Update Instructions in this section to point instead to the separate page set up for it. However, there needs to be a clear instruction here as to why a user might need to re-prepare their build environment. I, for one, have no idea why my build environment was broken. I had already followed those directions previously (as evidenced by the existence of the build folder structure on my system), so what broke them? I imagine something along the lines of:

“If you have not built the documentation before, or if you {have changed some miniscule aspect of your system | are incompetent like David T.}, it is usually necessary to reconfigure your build environment as outlined in Initializing Documentation Build Environment.”

Cheers,
David

> On Aug 17, 2018, at 3:25 PM, Frank H. Ellenberger <[hidden email]> wrote:
>
> Am 17.08.2018 um 09:18 schrieb Geert Janssens:
>> Op vrijdag 17 augustus 2018 08:41:05 CEST schreef David T. via gnucash-devel:
> :
>
>>> I’m not sure why there’s a “missing” in the initial command, and I don’t
>>> know where config.guess is supposed to be—and I won’t even try to guess.
>>>
>>> I would love to have some guidance.
>>>
>>
>> I went to look at the wiki page and unfortunately it's incomplete. You get
>> this error because a few essential commands have been omitted.
>>
>> I have added a section that should fill the gap. Can you proofread this:
>> https://wiki.gnucash.org/wiki/
>> Documentation_Update_Instructions#Prepare_The_Build_Directory
>> And report back any issues you experience ?
>>
>> It's written these steps are usually done early in in the set up process, but
>> you can still run them right now and then retry the validation.
>>
>> Geert
>
> Yeah, the missing section got lost in
> https://wiki.gnucash.org/wiki/index.php?title=Documentation_Update_Instructions&type=revision&diff=13215&oldid=12785
>
> OTOH it was a major improvement of the readability.
>
> Regards
> Frank
>

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

Re: [GNC-dev] Documentation update problems

GnuCash - Dev mailing list
Hello,

Can anyone give me clear language on when and why a documentation creator would need to reissue the commands in Initializing Documentation Build Environment? I’d like to clear this issue up on the wiki before it gets lost.

David

> On Sep 14, 2018, at 10:21 AM, David T. <[hidden email]> wrote:
>
> Frank, Geert,
>
> I am finally following up on this thread, and I’d like to note that the information that Frank says “got lost,” and which Geert has re-entered on this page were actually moved to a different page (https://wiki.gnucash.org/wiki/Initializing_Documentation_Build_Environment <https://wiki.gnucash.org/wiki/Initializing_Documentation_Build_Environment>) and the reference to this information was moved up to Section 2. Setting Up Your System.
>
> Here we have an example of how duplicative information ends up in our ecosystem!
>
> For the future, we should change the Documentation Update Instructions in this section to point instead to the separate page set up for it. However, there needs to be a clear instruction here as to why a user might need to re-prepare their build environment. I, for one, have no idea why my build environment was broken. I had already followed those directions previously (as evidenced by the existence of the build folder structure on my system), so what broke them? I imagine something along the lines of:
>
> “If you have not built the documentation before, or if you {have changed some miniscule aspect of your system | are incompetent like David T.}, it is usually necessary to reconfigure your build environment as outlined in Initializing Documentation Build Environment.”
>
> Cheers,
> David
>
>> On Aug 17, 2018, at 3:25 PM, Frank H. Ellenberger <[hidden email] <mailto:[hidden email]>> wrote:
>>
>> Am 17.08.2018 um 09:18 schrieb Geert Janssens:
>>> Op vrijdag 17 augustus 2018 08:41:05 CEST schreef David T. via gnucash-devel:
>> :
>>
>>>> I’m not sure why there’s a “missing” in the initial command, and I don’t
>>>> know where config.guess is supposed to be—and I won’t even try to guess.
>>>>
>>>> I would love to have some guidance.
>>>>
>>>
>>> I went to look at the wiki page and unfortunately it's incomplete. You get
>>> this error because a few essential commands have been omitted.
>>>
>>> I have added a section that should fill the gap. Can you proofread this:
>>> https://wiki.gnucash.org/wiki/ <https://wiki.gnucash.org/wiki/>
>>> Documentation_Update_Instructions#Prepare_The_Build_Directory
>>> And report back any issues you experience ?
>>>
>>> It's written these steps are usually done early in in the set up process, but
>>> you can still run them right now and then retry the validation.
>>>
>>> Geert
>>
>> Yeah, the missing section got lost in
>> https://wiki.gnucash.org/wiki/index.php?title=Documentation_Update_Instructions&type=revision&diff=13215&oldid=12785 <https://wiki.gnucash.org/wiki/index.php?title=Documentation_Update_Instructions&type=revision&diff=13215&oldid=12785>
>>
>> OTOH it was a major improvement of the readability.
>>
>> Regards
>> Frank
>>
>

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

Re: [GNC-dev] Documentation update problems

Frank H. Ellenberger-3
Hi David,

Am 17.09.18 um 14:59 schrieb David T.:
> Hello,
>
> Can anyone give me clear language on when and why a documentation creator would need to reissue the commands in Initializing Documentation Build Environment? I’d like to clear this issue up on the wiki before it gets lost.
>
> David

because of some general confusion about the term make i.e. in
https://wiki.gnucash.org/wiki/The_Make_Utility, I created recently
https://wiki.gnucash.org/wiki/Build_Tools. It might still be incomplete
or contain errors, so improvements are welcome. Feel free to link it,
where ever required.

You might also counter check the recent changes in
Documentation_Update_Instructions:
https://wiki.gnucash.org/wiki/index.php?title=Documentation_Update_Instructions&type=revision&diff=14469&oldid=13948

and other pages of
https://wiki.gnucash.org/wiki/Category:Development .

N.B.: It would be nice, if you would add categories to
https://wiki.gnucash.org/wiki/Initializing_Documentation_Build_Environment

>> On Sep 14, 2018, at 10:21 AM, David T. <[hidden email]> wrote:
>>
>> Frank, Geert,
>>
>> I am finally following up on this thread, and I’d like to note that the information that Frank says “got lost,” and which Geert has re-entered on this page were actually moved to a different page (https://wiki.gnucash.org/wiki/Initializing_Documentation_Build_Environment <https://wiki.gnucash.org/wiki/Initializing_Documentation_Build_Environment>) and the reference to this information was moved up to Section 2. Setting Up Your System.
>>
>> Here we have an example of how duplicative information ends up in our ecosystem!

That is a nice example, why you should make smaller changes. Instead of
"Major rewrite of entire page" it would be better readable, if you would
use separate steps of logical units:
Move Section x in a new page;
Move section y to appropriate position;
Rewordening of section z; ...

:

Regards
Frank

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

Re: [GNC-dev] Documentation update problems

GnuCash - Dev mailing list
Frank,

> On Sep 17, 2018, at 10:47 AM, Frank H. Ellenberger <[hidden email]> wrote:
>
> Hi David,
>
> Am 17.09.18 um 14:59 schrieb David T.:
>> Hello,
>>
>> Can anyone give me clear language on when and why a documentation creator would need to reissue the commands in Initializing Documentation Build Environment? I’d like to clear this issue up on the wiki before it gets lost.
>>
>> David
>
> because of some general confusion about the term make i.e. in
> https://wiki.gnucash.org/wiki/The_Make_Utility, I created recently
> https://wiki.gnucash.org/wiki/Build_Tools. It might still be incomplete
> or contain errors, so improvements are welcome. Feel free to link it,
> where ever required.

I worked a bit on Build Tools to make the flow seem more natural; see whether you agree.

With the rearrangement, I remain unclear on the last portion of the Autotools section, beginning with “So there remain 3 basic steps”

Does the following changed text capture your intent?


----------------
When using Autotools, there are 3 commonly-used commands:

• autogen.sh, which should be run after you check out a copy of the repository.
• configure [options], which should be run after you install updates of your tools {not sure which tools?} or modify either makefile.am or configure.ac
• make <target>, which is run after making edits. Common targets are all, check, and install.

Note that which build directory you use will affect the scope and output of your command.
----------------

I will note that for me, I *still* don’t know when I am required to re-run autogen.sh or configure; is there any downside to simply running them every time I mess around with the docs?

David

P.S. - As a professionally-trained librarian, I hesitate to engage in categorization of the wiki. I am not prepared to develop a logical taxonomy for the wiki at this time, and half-baked taxonomies grate upon my sensibilities.


>
> You might also counter check the recent changes in
> Documentation_Update_Instructions:
> https://wiki.gnucash.org/wiki/index.php?title=Documentation_Update_Instructions&type=revision&diff=14469&oldid=13948
>
> and other pages of
> https://wiki.gnucash.org/wiki/Category:Development .
>
> N.B.: It would be nice, if you would add categories to
> https://wiki.gnucash.org/wiki/Initializing_Documentation_Build_Environment
>
>>> On Sep 14, 2018, at 10:21 AM, David T. <[hidden email]> wrote:
>>>
>>> Frank, Geert,
>>>
>>> I am finally following up on this thread, and I’d like to note that the information that Frank says “got lost,” and which Geert has re-entered on this page were actually moved to a different page (https://wiki.gnucash.org/wiki/Initializing_Documentation_Build_Environment <https://wiki.gnucash.org/wiki/Initializing_Documentation_Build_Environment>) and the reference to this information was moved up to Section 2. Setting Up Your System.
>>>
>>> Here we have an example of how duplicative information ends up in our ecosystem!
>
> That is a nice example, why you should make smaller changes. Instead of
> "Major rewrite of entire page" it would be better readable, if you would
> use separate steps of logical units:
> Move Section x in a new page;
> Move section y to appropriate position;
> Rewordening of section z; ...
>
> :
>
> Regards
> Frank
>

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

Re: [GNC-dev] Documentation update problems

John Ralls-2


> On Sep 17, 2018, at 8:24 AM, David T. via gnucash-devel <[hidden email]> wrote:
>
> Frank,
>
>> On Sep 17, 2018, at 10:47 AM, Frank H. Ellenberger <[hidden email]> wrote:
>>
>> Hi David,
>>
>> Am 17.09.18 um 14:59 schrieb David T.:
>>> Hello,
>>>
>>> Can anyone give me clear language on when and why a documentation creator would need to reissue the commands in Initializing Documentation Build Environment? I’d like to clear this issue up on the wiki before it gets lost.
>>>
>>> David
>>
>> because of some general confusion about the term make i.e. in
>> https://wiki.gnucash.org/wiki/The_Make_Utility, I created recently
>> https://wiki.gnucash.org/wiki/Build_Tools. It might still be incomplete
>> or contain errors, so improvements are welcome. Feel free to link it,
>> where ever required.
>
> I worked a bit on Build Tools to make the flow seem more natural; see whether you agree.
>
> With the rearrangement, I remain unclear on the last portion of the Autotools section, beginning with “So there remain 3 basic steps”
>
> Does the following changed text capture your intent?
>
>
> ----------------
> When using Autotools, there are 3 commonly-used commands:
>
> • autogen.sh, which should be run after you check out a copy of the repository.
> • configure [options], which should be run after you install updates of your tools {not sure which tools?} or modify either makefile.am or configure.ac
> • make <target>, which is run after making edits. Common targets are all, check, and install.
>
> Note that which build directory you use will affect the scope and output of your command.
> ----------------
>
> I will note that for me, I *still* don’t know when I am required to re-run autogen.sh or configure; is there any downside to simply running them every time I mess around with the docs?
>
> David
>
> P.S. - As a professionally-trained librarian, I hesitate to engage in categorization of the wiki. I am not prepared to develop a logical taxonomy for the wiki at this time, and half-baked taxonomies grate upon my sensibilities.

David,

Run autogen.sh any time configure.ac or any Makefile.am changes. That might be because you changed it yourself or because someone else committed a change in git. There’s no harm in running it even if it’s not required, so the safest course is to do so after every pull.

Running autogen.sh creates a new configure script so you need to run configure after having run autogen.sh.  You also need to run it if you want to enable or disable building MOBI files.

Make all doesn’t do what one would expect in gnucash-docs: It doesn’t actually make anything. For docs you need to specify explicitly the document types you want, the choices being html, pdf, epub, mobi, and, on Windows only, chm.

Regards,
John Ralls

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

Re: [GNC-dev] Documentation update problems

Frank H. Ellenberger-3
In reply to this post by GnuCash - Dev mailing list
Am 17.09.18 um 17:24 schrieb David T.:

> Frank,
>
>> On Sep 17, 2018, at 10:47 AM, Frank H. Ellenberger <[hidden email]> wrote:
>>
>> Hi David,
>>
>> Am 17.09.18 um 14:59 schrieb David T.:
>>> Hello,
>>>
>>> Can anyone give me clear language on when and why a documentation creator would need to reissue the commands in Initializing Documentation Build Environment? I’d like to clear this issue up on the wiki before it gets lost.
>>>
>>> David
>>
>> because of some general confusion about the term make i.e. in
>> https://wiki.gnucash.org/wiki/The_Make_Utility, I created recently
>> https://wiki.gnucash.org/wiki/Build_Tools. It might still be incomplete
>> or contain errors, so improvements are welcome. Feel free to link it,
>> where ever required.
>
> I worked a bit on Build Tools to make the flow seem more natural; see whether you agree.

I am no fan of "__NOTOC__" because I want often send a deep link (read
page#section) to a user on IRC or MLs.

The order was historical, so one could add "CMake has the following
benefits over autotools ..."

> With the rearrangement, I remain unclear on the last portion of the Autotools section, beginning with “So there remain 3 basic steps”
>
> Does the following changed text capture your intent?
>
>
> ----------------
> When using Autotools, there are 3 commonly-used commands:
>
> • autogen.sh, which should be run after you check out a copy of the repository.
> • configure [options], which should be run after you install updates of your tools {not sure which tools?} or modify either makefile.am or configure.ac
> • make <target>, which is run after making edits. Common targets are all, check, and install.
>
> Note that which build directory you use will affect the scope and output of your command.
> ----------------
>
> I will note that for me, I *still* don’t know when I am required to re-run autogen.sh or configure; is there any downside to simply running them every time I mess around with the docs?

Because I saw the waekness, I worked on the section again. Can you reload?
And yes, apply Johns answer. I will leave the page for now.

> David
>
> P.S. - As a professionally-trained librarian, I hesitate to engage in categorization of the wiki. I am not prepared to develop a logical taxonomy for the wiki at this time, and half-baked taxonomies grate upon my sensibilities.

Yes, we might probably run in problems later. Despite it seems useful.
Just add from the list at
https://wiki.gnucash.org/wiki/Special:Categories
See also:
https://wiki.gnucash.org/wiki/Wiki_Conventions#Categories

Frank
---8<---

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

Re: [GNC-dev] Documentation update problems

GnuCash - Dev mailing list
Frank,

> On Sep 17, 2018, at 12:23 PM, Frank H. Ellenberger <[hidden email]> wrote:
>
> Am 17.09.18 um 17:24 schrieb David T.:
>>
>> I worked a bit on Build Tools to make the flow seem more natural; see whether you agree.
>
> I am no fan of "__NOTOC__" because I want often send a deep link (read
> page#section) to a user on IRC or MLs.

I think that the addition of a table of contents for a simple page is a waste of space, and pushes actual content off screen.

>
> The order was historical, so one could add "CMake has the following
> benefits over autotools …”
>

I changed the order so that information about compiling the program would be covered before the information about compiling the documentation. I don’t see any text that lists CMake benefits versus Autotools, so perhaps this is no longer an issue?

>> With the rearrangement, I remain unclear on the last portion of the Autotools section, beginning with “So there remain 3 basic steps”
>>
>> Does the following changed text capture your intent?
>>
>>
>> ----------------
>> When using Autotools, there are 3 commonly-used commands:
>>
>> • autogen.sh, which should be run after you check out a copy of the repository.
>> • configure [options], which should be run after you install updates of your tools {not sure which tools?} or modify either makefile.am or configure.ac
>> • make <target>, which is run after making edits. Common targets are all, check, and install.
>>
>> Note that which build directory you use will affect the scope and output of your command.
>> ----------------
>>
>> I will note that for me, I *still* don’t know when I am required to re-run autogen.sh or configure; is there any downside to simply running them every time I mess around with the docs?
>
> Because I saw the waekness, I worked on the section again. Can you reload?
> And yes, apply Johns answer. I will leave the page for now.

I saw your changes, but they continue to be unclear to me. Let me expand on my difficulties below

So there remain 3 basic steps:  <— it is unclear from the context what “remain” refers to. Remaining from what? Previously, we describe two “parts”; here we refer to “3 steps”—are these the same things?

<— in general, when listing “3 basic steps,” it is best for the enumerated list elements to *start* with what is being enumerated. That was a core part of the suggested text I provided above, and one I feel strongly about. As I decipher it, the three steps (which I referred to as “commands”) are autogen.sh, configure, and make. Is that correct?

After checking out of the repository run ./autogen.sh.
autogen.sh <https://github.com/Gnucash/gnucash-docs/blob/maint/autogen.sh> checks for the existence of autotools and (probably other build tools like intltool) and prepares your directory to use them.
After you updatedat least one of the in the file mentioned tools, you should rerun it.  <— there is at least a typo here; "at least one of the” … what? “in the file mentioned tools” … what is a “file mentioned tool”?
Decide, which build directory to use and run the following steps in your build dir.  <— I have a problem here, insofar as it sounds as if this advice applies to step 2, but is listed as a subsidiary of step 1. Or is this a more general explanation to the effect of the note text I provided in my earlier rewrite (see above)?
After you

installed updates of not in autogen.sh mentioned tools or used libraries or  <— I can’t make this out. Are you trying to say “installed updates in tools other than autogen.sh or installed other libraries”?
modified makefile.am or configure.ac
run configure [options].
Tip
configure --help will give you the full list of possible options.
Finally after your edits run make <target>. Some common targets are all, check, install.




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

Re: [GNC-dev] Documentation update problems

Frank H. Ellenberger-3
David,

Am 17.09.18 um 19:49 schrieb David T.:

> Frank,
>
>> On Sep 17, 2018, at 12:23 PM, Frank H. Ellenberger <[hidden email]> wrote:
>>
>> Am 17.09.18 um 17:24 schrieb David T.:
>>>
>>> I worked a bit on Build Tools to make the flow seem more natural; see whether you agree.
>>
>> I am no fan of "__NOTOC__" because I want often send a deep link (read
>> page#section) to a user on IRC or MLs.
>
> I think that the addition of a table of contents for a simple page is a waste of space, and pushes actual content off screen.

If I can not right-click->copy the link of the section, it is a waste of
my time. Guess wich one is cheaper.

>> The order was historical, so one could add "CMake has the following
>> benefits over autotools …”
>>
>
> I changed the order so that information about compiling the program would be covered before the information about compiling the documentation. I don’t see any text that lists CMake benefits versus Autotools, so perhaps this is no longer an issue?

Coming soon! ;-)
No I don't know if we ever will need it. But I feel, the CMake section
might probably need more extension. And I believe, the main audience of
the page might be documenters, because coders will more often already
know the content.

>>> With the rearrangement, I remain unclear on the last portion of the Autotools section, beginning with “So there remain 3 basic steps”
>>>
>>> Does the following changed text capture your intent?
>>>
>>>
>>> ----------------
>>> When using Autotools, there are 3 commonly-used commands:
>>>
>>> • autogen.sh, which should be run after you check out a copy of the repository.
>>> • configure [options], which should be run after you install updates of your tools {not sure which tools?} or modify either makefile.am or configure.ac
>>> • make <target>, which is run after making edits. Common targets are all, check, and install.
>>>
>>> Note that which build directory you use will affect the scope and output of your command.
>>> ----------------
>>>
>>> I will note that for me, I *still* don’t know when I am required to re-run autogen.sh or configure; is there any downside to simply running them every time I mess around with the docs?
>>
>> Because I saw the waekness, I worked on the section again. Can you reload?
>> And yes, apply Johns answer. I will leave the page for now.
>
> I saw your changes, but they continue to be unclear to me. Let me expand on my difficulties below
>
> So there remain 3 basic steps:  <— it is unclear from the context what “remain” refers to. Remaining from what? Previously, we describe two “parts”; here we refer to “3 steps”—are these the same things?

Before you checked out a git repo and optionally created a build
directory. (So let's move buil dir section up.) Then run the typical 3
steps of autotools Autogen flavour.

> <— in general, when listing “3 basic steps,” it is best for the enumerated list elements to *start* with what is being enumerated. That was a core part of the suggested text I provided above, and one I feel strongly about. As I decipher it, the three steps (which I referred to as “commands”) are autogen.sh, configure, and make. Is that correct?

yes

> After checking out of the repository run ./autogen.sh.
> autogen.sh <https://github.com/Gnucash/gnucash-docs/blob/maint/autogen.sh> checks for the existence of autotools and (probably other build tools like intltool) and prepares your directory to use them.
> After you updatedat least one of the in the file mentioned tools, you should rerun it.  <— there is at least a typo here; "at least one of the” … what? “in the file mentioned tools” … what is a “file mentioned tool”?

updated at least
autogen.sh is the file in which the tools are mentioned.

Hypothetical example: we want support gettext translations, then
autogen.sh gets a line "intltoolize" added, because intltool is the
library for which the project needs some initialization.

> Decide, which build directory to use and run the following steps in your build dir.  <— I have a problem here, insofar as it sounds as if this advice applies to step 2, but is listed as a subsidiary of step 1. Or is this a more general explanation to the effect of the note text I provided in my earlier rewrite (see above)?
move it before the 3 steps. (see above)

> After you
>
> installed updates of not in autogen.sh mentioned tools or used libraries or  <— I can’t make this out. Are you trying to say “installed updates in tools other than autogen.sh or installed other libraries”?

If your system got a new version of autotools, restart with autogen.sh,
if you got a new version of libxml, restart with configure. libxml is
not mentioned in autogen.sh.

> modified makefile.am or configure.ac
> run configure [options].
> Tip
> configure --help will give you the full list of possible options.
> Finally after your edits run make <target>. Some common targets are all, check, install.

Don't forget Johns answer.

Frank

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

Re: [GNC-dev] Documentation update problems

John Ralls-2
In reply to this post by GnuCash - Dev mailing list


> On Sep 17, 2018, at 10:49 AM, David T. via gnucash-devel <[hidden email]> wrote:
>
> Frank,
>
>> On Sep 17, 2018, at 12:23 PM, Frank H. Ellenberger <[hidden email]> wrote:
>>
>> Am 17.09.18 um 17:24 schrieb David T.:
>>>
>>> I worked a bit on Build Tools to make the flow seem more natural; see whether you agree.
>>
>> I am no fan of "__NOTOC__" because I want often send a deep link (read
>> page#section) to a user on IRC or MLs.
>
> I think that the addition of a table of contents for a simple page is a waste of space, and pushes actual content off screen.
>
>>
>> The order was historical, so one could add "CMake has the following
>> benefits over autotools …”
>>
>
> I changed the order so that information about compiling the program would be covered before the information about compiling the documentation. I don’t see any text that lists CMake benefits versus Autotools, so perhaps this is no longer an issue?
>
>>> With the rearrangement, I remain unclear on the last portion of the Autotools section, beginning with “So there remain 3 basic steps”
>>>
>>> Does the following changed text capture your intent?
>>>
>>>
>>> ----------------
>>> When using Autotools, there are 3 commonly-used commands:
>>>
>>> • autogen.sh, which should be run after you check out a copy of the repository.
>>> • configure [options], which should be run after you install updates of your tools {not sure which tools?} or modify either makefile.am or configure.ac
>>> • make <target>, which is run after making edits. Common targets are all, check, and install.
>>>
>>> Note that which build directory you use will affect the scope and output of your command.
>>> ----------------
>>>
>>> I will note that for me, I *still* don’t know when I am required to re-run autogen.sh or configure; is there any downside to simply running them every time I mess around with the docs?
>>
>> Because I saw the waekness, I worked on the section again. Can you reload?
>> And yes, apply Johns answer. I will leave the page for now.
>
> I saw your changes, but they continue to be unclear to me. Let me expand on my difficulties below
>
> So there remain 3 basic steps:  <— it is unclear from the context what “remain” refers to. Remaining from what? Previously, we describe two “parts”; here we refer to “3 steps”—are these the same things?
>
> <— in general, when listing “3 basic steps,” it is best for the enumerated list elements to *start* with what is being enumerated. That was a core part of the suggested text I provided above, and one I feel strongly about. As I decipher it, the three steps (which I referred to as “commands”) are autogen.sh, configure, and make. Is that correct?
>
> After checking out of the repository run ./autogen.sh.
> autogen.sh <https://github.com/Gnucash/gnucash-docs/blob/maint/autogen.sh> checks for the existence of autotools and (probably other build tools like intltool) and prepares your directory to use them.
> After you updatedat least one of the in the file mentioned tools, you should rerun it.  <— there is at least a typo here; "at least one of the” … what? “in the file mentioned tools” … what is a “file mentioned tool”?
> Decide, which build directory to use and run the following steps in your build dir.  <— I have a problem here, insofar as it sounds as if this advice applies to step 2, but is listed as a subsidiary of step 1. Or is this a more general explanation to the effect of the note text I provided in my earlier rewrite (see above)?
> After you
>
> installed updates of not in autogen.sh mentioned tools or used libraries or  <— I can’t make this out. Are you trying to say “installed updates in tools other than autogen.sh or installed other libraries”?
> modified makefile.am or configure.ac
> run configure [options].
> Tip
> configure --help will give you the full list of possible options.
> Finally after your edits run make <target>. Some common targets are all, check, install.
>

I've rewritten the page in a way that I hope is clearer and more correct for David to use as a starting point.

Regards,
John Ralls

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

Re: [GNC-dev] Documentation update problems

John Ralls-2
In reply to this post by Frank H. Ellenberger-3


> On Sep 17, 2018, at 11:56 AM, Frank H. Ellenberger <[hidden email]> wrote:
>
> David,
>
> Am 17.09.18 um 19:49 schrieb David T.:
>> Frank,
>>
>>> On Sep 17, 2018, at 12:23 PM, Frank H. Ellenberger <[hidden email]> wrote:
>>>
>>> Am 17.09.18 um 17:24 schrieb David T.:
>>>>
>>>> I worked a bit on Build Tools to make the flow seem more natural; see whether you agree.
>>>
>>> I am no fan of "__NOTOC__" because I want often send a deep link (read
>>> page#section) to a user on IRC or MLs.
>>
>> I think that the addition of a table of contents for a simple page is a waste of space, and pushes actual content off screen.
>
> If I can not right-click->copy the link of the section, it is a waste of
> my time. Guess wich one is cheaper.
>
>>> The order was historical, so one could add "CMake has the following
>>> benefits over autotools …”
>>>
>>
>> I changed the order so that information about compiling the program would be covered before the information about compiling the documentation. I don’t see any text that lists CMake benefits versus Autotools, so perhaps this is no longer an issue?
>
> Coming soon! ;-)
> No I don't know if we ever will need it. But I feel, the CMake section
> might probably need more extension. And I believe, the main audience of
> the page might be documenters, because coders will more often already
> know the content.
>
>>>> With the rearrangement, I remain unclear on the last portion of the Autotools section, beginning with “So there remain 3 basic steps”
>>>>
>>>> Does the following changed text capture your intent?
>>>>
>>>>
>>>> ----------------
>>>> When using Autotools, there are 3 commonly-used commands:
>>>>
>>>> • autogen.sh, which should be run after you check out a copy of the repository.
>>>> • configure [options], which should be run after you install updates of your tools {not sure which tools?} or modify either makefile.am or configure.ac
>>>> • make <target>, which is run after making edits. Common targets are all, check, and install.
>>>>
>>>> Note that which build directory you use will affect the scope and output of your command.
>>>> ----------------
>>>>
>>>> I will note that for me, I *still* don’t know when I am required to re-run autogen.sh or configure; is there any downside to simply running them every time I mess around with the docs?
>>>
>>> Because I saw the waekness, I worked on the section again. Can you reload?
>>> And yes, apply Johns answer. I will leave the page for now.
>>
>> I saw your changes, but they continue to be unclear to me. Let me expand on my difficulties below
>>
>> So there remain 3 basic steps:  <— it is unclear from the context what “remain” refers to. Remaining from what? Previously, we describe two “parts”; here we refer to “3 steps”—are these the same things?
>
> Before you checked out a git repo and optionally created a build
> directory. (So let's move buil dir section up.) Then run the typical 3
> steps of autotools Autogen flavour.
>
>> <— in general, when listing “3 basic steps,” it is best for the enumerated list elements to *start* with what is being enumerated. That was a core part of the suggested text I provided above, and one I feel strongly about. As I decipher it, the three steps (which I referred to as “commands”) are autogen.sh, configure, and make. Is that correct?
>
> yes
>
>> After checking out of the repository run ./autogen.sh.
>> autogen.sh <https://github.com/Gnucash/gnucash-docs/blob/maint/autogen.sh> checks for the existence of autotools and (probably other build tools like intltool) and prepares your directory to use them.
>> After you updatedat least one of the in the file mentioned tools, you should rerun it.  <— there is at least a typo here; "at least one of the” … what? “in the file mentioned tools” … what is a “file mentioned tool”?
>
> updated at least
> autogen.sh is the file in which the tools are mentioned.
>
> Hypothetical example: we want support gettext translations, then
> autogen.sh gets a line "intltoolize" added, because intltool is the
> library for which the project needs some initialization.
>
>> Decide, which build directory to use and run the following steps in your build dir.  <— I have a problem here, insofar as it sounds as if this advice applies to step 2, but is listed as a subsidiary of step 1. Or is this a more general explanation to the effect of the note text I provided in my earlier rewrite (see above)?
> move it before the 3 steps. (see above)
>
>> After you
>>
>> installed updates of not in autogen.sh mentioned tools or used libraries or  <— I can’t make this out. Are you trying to say “installed updates in tools other than autogen.sh or installed other libraries”?
>
> If your system got a new version of autotools, restart with autogen.sh,
> if you got a new version of libxml, restart with configure. libxml is
> not mentioned in autogen.sh.
>
>> modified makefile.am or configure.ac
>> run configure [options].
>> Tip
>> configure --help will give you the full list of possible options.
>> Finally after your edits run make <target>. Some common targets are all, check, install.
>

There's no need to rerun autogen.sh because you've updated one of the autotools components. Once configure is generated it's independent of autoconf, automake, and the rest. The only external change that might get one to rerun autogen.sh would be a libtool update because it would insert the newer ltmain.sh... but that only applies to building code, not documentation. Intltool isn't actively maintained so intltoolize isn't going to change.

Regards,
John Ralls

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

Re: [GNC-dev] Documentation update problems

GnuCash - Dev mailing list
In reply to this post by John Ralls-2
John,

Thank you for stepping in. This looks much better now, and I believe I understand it, maybe. I have added a link to this page from the broader Documentation Update Instructions page (so it won’t be lonely).

David

> On Sep 17, 2018, at 3:04 PM, John Ralls <[hidden email]> wrote:
>
>
>
>> On Sep 17, 2018, at 10:49 AM, David T. via gnucash-devel <[hidden email]> wrote:
>>
>> Frank,
>>
>>> On Sep 17, 2018, at 12:23 PM, Frank H. Ellenberger <[hidden email]> wrote:
>>>
>>> Am 17.09.18 um 17:24 schrieb David T.:
>>>>
>>>> I worked a bit on Build Tools to make the flow seem more natural; see whether you agree.
>>>
>>> I am no fan of "__NOTOC__" because I want often send a deep link (read
>>> page#section) to a user on IRC or MLs.
>>
>> I think that the addition of a table of contents for a simple page is a waste of space, and pushes actual content off screen.
>>
>>>
>>> The order was historical, so one could add "CMake has the following
>>> benefits over autotools …”
>>>
>>
>> I changed the order so that information about compiling the program would be covered before the information about compiling the documentation. I don’t see any text that lists CMake benefits versus Autotools, so perhaps this is no longer an issue?
>>
>>>> With the rearrangement, I remain unclear on the last portion of the Autotools section, beginning with “So there remain 3 basic steps”
>>>>
>>>> Does the following changed text capture your intent?
>>>>
>>>>
>>>> ----------------
>>>> When using Autotools, there are 3 commonly-used commands:
>>>>
>>>> • autogen.sh, which should be run after you check out a copy of the repository.
>>>> • configure [options], which should be run after you install updates of your tools {not sure which tools?} or modify either makefile.am or configure.ac
>>>> • make <target>, which is run after making edits. Common targets are all, check, and install.
>>>>
>>>> Note that which build directory you use will affect the scope and output of your command.
>>>> ----------------
>>>>
>>>> I will note that for me, I *still* don’t know when I am required to re-run autogen.sh or configure; is there any downside to simply running them every time I mess around with the docs?
>>>
>>> Because I saw the waekness, I worked on the section again. Can you reload?
>>> And yes, apply Johns answer. I will leave the page for now.
>>
>> I saw your changes, but they continue to be unclear to me. Let me expand on my difficulties below
>>
>> So there remain 3 basic steps:  <— it is unclear from the context what “remain” refers to. Remaining from what? Previously, we describe two “parts”; here we refer to “3 steps”—are these the same things?
>>
>> <— in general, when listing “3 basic steps,” it is best for the enumerated list elements to *start* with what is being enumerated. That was a core part of the suggested text I provided above, and one I feel strongly about. As I decipher it, the three steps (which I referred to as “commands”) are autogen.sh, configure, and make. Is that correct?
>>
>> After checking out of the repository run ./autogen.sh.
>> autogen.sh <https://github.com/Gnucash/gnucash-docs/blob/maint/autogen.sh> checks for the existence of autotools and (probably other build tools like intltool) and prepares your directory to use them.
>> After you updatedat least one of the in the file mentioned tools, you should rerun it.  <— there is at least a typo here; "at least one of the” … what? “in the file mentioned tools” … what is a “file mentioned tool”?
>> Decide, which build directory to use and run the following steps in your build dir.  <— I have a problem here, insofar as it sounds as if this advice applies to step 2, but is listed as a subsidiary of step 1. Or is this a more general explanation to the effect of the note text I provided in my earlier rewrite (see above)?
>> After you
>>
>> installed updates of not in autogen.sh mentioned tools or used libraries or  <— I can’t make this out. Are you trying to say “installed updates in tools other than autogen.sh or installed other libraries”?
>> modified makefile.am or configure.ac
>> run configure [options].
>> Tip
>> configure --help will give you the full list of possible options.
>> Finally after your edits run make <target>. Some common targets are all, check, install.
>>
>
> I've rewritten the page in a way that I hope is clearer and more correct for David to use as a starting point.
>
> Regards,
> John Ralls
>

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

Re: [GNC-dev] Documentation update problems

David Cousens
John, David, Frank

I wonder at the value of the Build Tools page as a separate orphan entity
given the more detailed instructions given in the Building Gnucash page.
There is a fairly good example of dupllcation with it and the following for
the Gnucash progarm build.

https://wiki.gnucash.org/wiki/Building

and the breakout from it for recent Ubuntu versions

https://wiki.gnucash.org/wiki/BuildUbuntu16.04

The main building page is a massive tome. I did start breaking out some
parts of it into smaller logical chunks when I updated the BuildUbuntu16.04
( which covers 16.04, 18.04 and Linux MInt 18 and 19 in effect.). The Build
Tools page may be a logical breakout from there with some of the detail in
the first page cut into it. There is also a short summary recipe for
building the Docs at the end of the BuildUbuntu16.04 page which lacks detail
but does work on Ubuntu and most linux distros. It has no details about the
dependencies in it though.

Would a page on building the docs be better as a breakout from the main
building Gnucash page perhaps with a shared section on the build tools
referenced from both. For build instructions I ususaly find the recipe the
most useful bit with explantions of the specific tools as breakouts. If you
need the information and background you can follow the links. If you only do
a build occasionally you follow the recipe.  I.e only read the manual when
you have to.

David Cousens



-----
David Cousens
--
Sent from: http://gnucash.1415818.n4.nabble.com/GnuCash-Dev-f1435356.html
_______________________________________________
gnucash-devel mailing list
[hidden email]
https://lists.gnucash.org/mailman/listinfo/gnucash-devel
David Cousens
Reply | Threaded
Open this post in threaded view
|

Re: [GNC-dev] Documentation update problems

Frank H. Ellenberger-3
Hi David Cousens,

In general the wiki needs some modularization to reduce redundancy. That
means, where ever you see similar text, create a new page with the best
parts and replace the pold texts with a link.

OTOH there are different target groups from expirienced coders to less
techie first time contributors to the documentation or translation.

The special art is now to find the right balance.

Am 18.09.18 um 10:19 schrieb David Cousens:
> John, David, Frank
>
> I wonder at the value of the Build Tools page as a separate orphan entity
> given the more detailed instructions given in the Building Gnucash page.

It has been an orphan until yesterday because it has been a draft with
the intension to clarify some confusion about terms around "make". After
David T. confirmed the usability, we should replace similar texts in
other pages by a link, e.g.
https://wiki.gnucash.org/wiki/The_Make_Utility

> There is a fairly good example of dupllcation with it and the following for
> the Gnucash progarm build.
>
> https://wiki.gnucash.org/wiki/Building
>
> and the breakout from it for recent Ubuntu versions
>
> https://wiki.gnucash.org/wiki/BuildUbuntu16.04

In general I do not watch distro specific pages. While other created one
page, Ubunteros are "spamming" the wiki:
BuildGutsy, BuildUbuntu16.04, UbuntuShortcuts, Unity Shortcuts ...

Perhaps you can do some cleanup: Is Gutsy outdated?

> The main building page is a massive tome. I did start breaking out some
> parts of it into smaller logical chunks when I updated the BuildUbuntu16.04
> ( which covers 16.04, 18.04 and Linux MInt 18 and 19 in effect.).

Shouldn't it be renamed to BuildUbuntu then?

> The Build Tools page may be a logical breakout from there with some
> of the detail in the first page cut into it. There is also a short
> summary recipe for building the Docs at the end of the
> BuildUbuntu16.04 page which lacks detail but does work on Ubuntu and
> most linux distros. It has no details about the dependencies in it
> though.
ISTR there are some fine parts, which should either go to Building or
get their own page linked from both.

> Would a page on building the docs be better as a breakout from the main
> building Gnucash page perhaps with a shared section on the build tools
> referenced from both.

The Docs update page was once created by a documenter, who found the
general build page ways to complicate and was for a long time almost
untouched by code developers.

> For build instructions I ususaly find the recipe the
> most useful bit with explantions of the specific tools as breakouts. If you
> need the information and background you can follow the links. If you only do
> a build occasionally you follow the recipe.  I.e only read the manual when
> you have to.
>
> David Cousens

Frank

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

Re: [GNC-dev] Documentation update problems

Adrien Monteleone-2


> On Sep 18, 2018, at 7:53 AM, Frank H. Ellenberger <[hidden email]> wrote:
>
>
> Perhaps you can do some cleanup: Is Gutsy outdated?

That was version 7.10 of Ubuntu, that is, released October 2007. By far, it is no longer supported by Canonical. (wasn’t even a Long Term Support release) And there is not even a hardware reason that anyone should be running it. I don’t even think the repos for it are even available any longer.

The oldest supported Ubuntu version is 14.04 (and then only until next April) I shouldn’t think any build instructions are necessary (unless in an archived page if desired) for anything older than this.

>
>> The main building page is a massive tome. I did start breaking out some
>> parts of it into smaller logical chunks when I updated the BuildUbuntu16.04
>> ( which covers 16.04, 18.04 and Linux MInt 18 and 19 in effect.).
>
> Shouldn’t it be renamed to BuildUbuntu then?

I agree, the link text/page title is confusing and there have already been questions about what instructions to use for building on 18.04.(yes, I see that it says this is for 18.04 as well, but clearly someone didn’t or they wouldn’t have asked)

If replacing content with a link to a dedicated page is desired practice for cleaning up the wiki, then I’d propose all of the material for building on Ubuntu be moved to that page, that it be renamed simply BuildUbuntu and that the main build page be left with a link to it for the Ubuntu section. As it is, the original build page still contains long outdated info. I would have instead expected to see the most current instructions there and then maybe a link for older versions.

Along with that, if older material for older systems and versions isn’t going to be moved to its own ‘archive’ page, then it should always appear down the page in chronological order. The current state of the build instructions is a bit messy in that regard.

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

Re: [GNC-dev] Documentation update problems

GnuCash - Dev mailing list
Hello,

I have a general question about building. Forgive me if this is naive. The last time I used Linux was last century, and I believe that Linux has changed just a tad since then.

Since GnuCash is now developed over git, can't users|developers|writers|yetis use git for most distros to obtain source code and compile it on their machines? IOW, rather than offer voluminous directions on how to obtain the sources and compile GnuCash on every variant of YetiCompute, could we simply advise the majority of the community (yetis included) to use git to clone our repos and compile using git? It seems to me to be a colossal waste of community effort to attempt to account for every flavor of every distro. I contrast this with the (IMHO correct) stance on encryption, in which circumstance we advise users to find appropriate encryption tools, rather than build a half-crap version of our own.

Focusing our efforts on *a* GnuCash Way of building the program would simplify the wiki immensely.

> On Sep 18, 2018, at 12:18 PM, Adrien Monteleone <[hidden email]> wrote:
>>
>>> The main building page is a massive tome. I did start breaking out some
>>> parts of it into smaller logical chunks when I updated the BuildUbuntu16.04
>>> ( which covers 16.04, 18.04 and Linux MInt 18 and 19 in effect.).
>>
>> Shouldn’t it be renamed to BuildUbuntu then?
>
> I agree, the link text/page title is confusing and there have already been questions about what instructions to use for building on 18.04.(yes, I see that it says this is for 18.04 as well, but clearly someone didn’t or they wouldn’t have asked)

If we continue with the Massive Tome Approach, I would recommend a title of “Building on Ubuntu"

>
> If replacing content with a link to a dedicated page is desired practice for cleaning up the wiki, then I’d propose all of the material for building on Ubuntu be moved to that page, that it be renamed simply BuildUbuntu and that the main build page be left with a link to it for the Ubuntu section. As it is, the original build page still contains long outdated info. I would have instead expected to see the most current instructions there and then maybe a link for older versions.
>
> Along with that, if older material for older systems and versions isn’t going to be moved to its own ‘archive’ page, then it should always appear down the page in chronological order. The current state of the build instructions is a bit messy in that regard.

Older content should be removed altogether, not archived.


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

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

Re: [GNC-dev] Documentation update problems

Adrien Monteleone-2


> On Sep 18, 2018, at 12:16 PM, David T. <[hidden email]> wrote:
>
>>
>> Along with that, if older material for older systems and versions isn’t going to be moved to its own ‘archive’ page, then it should always appear down the page in chronological order. The current state of the build instructions is a bit messy in that regard.
>
> Older content should be removed altogether, not archived.

I should have specified that what I meant by ‘older material’ was the instructions for say building 2.6.x using Autotools instead of Cmake, or building either 2.6.x or 3.x on 14.04. (which admittedly will be unsupported in less than 8 months) Obsolete instructions should be removed entirely. But if something changes between now and say Ubuntu 20.04 that would necessitate different treatment, then the current instructions should be archived or bumped down the page, not removed, because 16.04 & 18.04 will still be supported and in active use.

Though, and I may be misunderstanding the GnuCash support policy, if 2.6.x is not being actively developed (is that not the same thing as ‘not supported’?) then the recipe should be for 3.x with Cmake only.

As for different architectures and distros, I should think any notes are just specific quirks based on what may or may not be on the system by default. I should think the dependencies are what they are, and the recipe should be the same. (disclosure - I’m not familiar with building on a regular basis on different systems other than MacOS and Ubuntu/Debian)

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