Re: [GNC-dev] Yet another documentation compiling oddity

[Geert Janssens]

Op vrijdag 14 september 2018 16:55:33 CEST schreef David T. via gnucash-devel:
> Hello,
> 
> As I am toiling through the depths of the documentation generation process,
> I am struck by the fact that the base page of the Help is “help.html”,
> while the base page for the guide is “index.html”.
> 
> For consistency, I suggest naming the guide base page “guide.html”;

If we change it for consistency I'm inclined to rename both to index.html. That 
will help web 
servers to open the correct start page if users omit it and would be consistent 
with how 
websites are generally set up.

It's been a long while since last time I was focusing on the documentation 
sources. I remember 
noticing the inconsistency back then as well. But for some reason I had decided 
not to change it. 
I know that if we do so we'll have to make adjustments to the integrated help 
and guide display 
on Macos, to the build system for gnucash on Windows, for the nightly build 
script for 
documentation and for the website. Perhaps I considered that too much effort 
back then. I'm 
less worried about that now and I like consistency so I'll see if I can 
coordinate this change with 
Derek.

> moreover, I suggest having a simple “index.html” placed in the
> documentation root folder (for me, that will be gnucash-docs/build”):

I actually like this idea. It would give a local webpage to quickly open all 
available 
documentation in the current build environment.

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

Re: [GNC-dev] Yet another documentation compiling oddity

[Adrien Monteleone]

Interesting. I’ll investigate. I’ve never had an issue that I’m aware of. If 
the server won’t even let you get there due to the directive...?

Regards,
Adrien

> On Sep 14, 2018, at 5:38 PM, John Ralls  wrote:
> 
> It's my understanding that that's less than perfect. It's standard practice 
> in the the CMS world to put poisoned index.html files in directories where 
> you don't want browsers poking their noses.
> 
> Regards,
> John Ralls


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

Re: [GNC-dev] Git Questions With Documentation

[David T. via gnucash-devel]

David,

A couple of points.

Why not put this directly into the new chapter in the Guide, rather than into 
the Help? This is precisely the kind of detailed information that belongs IMHO 
in the Guide rather than Help. I know it’s not in Maint yet, but it will be 
shortly.

Next, in the interest of completeness, your list should include *all* import 
formats, and stub sections for those formats later on. Someone else can provide 
detail later on, but the basic description needs to be complete.

Otherwise, this looks great. Thanks!

David T.


> On Sep 14, 2018, at 9:29 PM, David Cousens  wrote:
> 
> David ,
> 
> I have completed the import section as an addition to the Help  manual  CH
> 6. I have put a pull request to gnucash-docs on Github to incorporate it
> into maint as the changes for the multiple selection may possibly go into
> the next release.
> 
> Once it has been pulled into the main Github repository as Bug 796856.  I
> think you will be able to get it by rebasing your repository to the maint
> branch of the gnucash-docs Github repository. I only know enough git to be
> dangerous so am not the best source of advice on how exactly to do that at
> this stage. I am starting to understand what is going on now. I have used
> git for quite a few years to my own repository but am now getting used to
> the 3 way operation for code and documentation updates to GnuCash.
> 
> David Cousens
> 
> 
> 
> -
> David Cousens
> --
> Sent from: http://gnucash.1415818.n4.nabble.com/GnuCash-Dev-f1435356.html
> ___
> 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] Git Questions With Documentation

[David Cousens]

David ,

I have completed the import section as an addition to the Help  manual  CH
6. I have put a pull request to gnucash-docs on Github to incorporate it
into maint as the changes for the multiple selection may possibly go into
the next release.

Once it has been pulled into the main Github repository as Bug 796856.  I
think you will be able to get it by rebasing your repository to the maint
branch of the gnucash-docs Github repository. I only know enough git to be
dangerous so am not the best source of advice on how exactly to do that at
this stage. I am starting to understand what is going on now. I have used
git for quite a few years to my own repository but am now getting used to
the 3 way operation for code and documentation updates to GnuCash.

David Cousens



-
David Cousens
--
Sent from: http://gnucash.1415818.n4.nabble.com/GnuCash-Dev-f1435356.html
___
gnucash-devel mailing list
gnucash-devel@gnucash.org
https://lists.gnucash.org/mailman/listinfo/gnucash-devel

Re: [GNC-dev] Gnome HIG

[John Ralls]

We're probably pretty compliant with the Gnome 2.0 HIG, but the Gnome HIG has 
changed over the years and GnuCash's UI hasn't. Just switching to Gtk3 probably 
got us some updates just because Gtk is what implements the HIG, but that would 
have been largely inadvertent.

For the purposes of the documentation I don't think we should be making any 
claims like that.

Regards,
John Ralls


> On Sep 14, 2018, at 11:57 AM, David T. via gnucash-devel 
>  wrote:
> 
> Hello,
> 
> In the course of another arduous and lengthy thread, the question of the 
> Gnome HIG came up. I attach the text in question below.
> 
> My question is whether the Guide needs changing at 1.2.1, where it says:
> Easy to Use Menus: GnuCash menus conform to the GNOME Human Interface 
> Guidelines. This means that they are simple and similar in appearance to many 
> other GNOME applications. 
> 
> Is this statement inaccurate? Should it be removed?
> 
> David
> 
>  
> Previous discussion:
> 
> I don't know about allowing room for it, but it's pretty far in the future 
> because we still have too many Gnome dependencies in the core and too many 
> MVC violations to be able to implement a different toolkit.
> 
> Regards,
> John Ralls
> 
> 
>> On Sep 11, 2018, at 10:23 AM, Adrien Monteleone 
>> mailto:adrien.montele...@lusfiber.net>> 
>> wrote:
>> 
>> Then I misunderstood some earlier discussions about the UI, at least with 
>> respect to Linux. What toolkit is envisioned to be used? What layout 
>> principles? Or are those questions so far in the future as to not be worth 
>> spending time allowing room for?
>> 
>> Regards,
>> Adrien
>> 
>>> On Sep 11, 2018, at 12:18 PM, John Ralls >> > wrote:
>>> 
>>> 
>>> 
 On Sep 11, 2018, at 10:09 AM, Adrien Monteleone 
 mailto:adrien.montele...@lusfiber.net>> 
 wrote:
 
 
 
> On Sep 11, 2018, at 8:13 AM, David T. via gnucash-devel 
> mailto:gnucash-devel@gnucash.org>> wrote:
> 
> In other words, unless there is a change in function, there is no need to 
> change the functional description. It seems to me that putting text that 
> doesn’t change into code is essentially a one-time process. Not 
> necessarily easy, but once completed, not particularly obtrusive. Putting 
> the functional description into code has the added benefit, perhaps, of 
> alerting developers to the fact that if they change a feature, the 
> description (right there in the code) needs an update as well.
 
 While the principles might not change, or even the name/label of certain 
 buttons, the UI layout (where those buttons are, the fact that they are 
 buttons instead of menu entries, etc.) will very likely change as the 
 Gnome HIG is more faithfully implemented. But those code changes shouldn’t 
 affect anything generally in the Guide, and should auto update the context 
 help if it is drawn from the code itself. If not, then consider that 
 attempts to corral GnuCash within the confines of the Gnome HIG, will 
 produce such changes you’re thinking won’t happen.
>>> 
>>> Why do you think we're going to "more faithfully implement" the Gnome HIG? 
>>> One of our long-term goals is to remove our Gnome dependencies. 
>>> 
>>> 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] Yet another documentation compiling oddity

[John Ralls]

> On Sep 14, 2018, at 9:24 AM, Adrien Monteleone 
>  wrote:
> 
> 
> 
>> On Sep 14, 2018, at 11:10 AM, John Ralls  wrote:
>> 
>> 
>> We should change the name of gnucash-guide/index.html, but we should also 
>> insert an index.html into every directory that raises an error to prevent 
>> direct browsing; user access should be via 
>> https://www.gnucash.org/docs.phtml  
>> only. 
> 
> By this do you mean you don’t want people to see the contents of the 
> directory?
> 
> If that’s the case, you can accomplish that with an .htaccess directive as 
> follows:
> 
> # disable directory browsing
> Options All -Indexes
> 
> You shouldn’t need ‘dummy’ index.html files.

It's my understanding that that's less than perfect. It's standard practice in 
the the CMS world to put poisoned index.html files in directories where you 
don't want browsers poking their noses.

Regards,
John Ralls

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

[GNC-dev] Gnome HIG

[David T. via gnucash-devel]

Hello,

In the course of another arduous and lengthy thread, the question of the Gnome 
HIG came up. I attach the text in question below.

My question is whether the Guide needs changing at 1.2.1, where it says:
Easy to Use Menus: GnuCash menus conform to the GNOME Human Interface 
Guidelines. This means that they are simple and similar in appearance to many 
other GNOME applications. 

Is this statement inaccurate? Should it be removed?

David

 
Previous discussion:

I don't know about allowing room for it, but it's pretty far in the future 
because we still have too many Gnome dependencies in the core and too many MVC 
violations to be able to implement a different toolkit.

Regards,
John Ralls


> On Sep 11, 2018, at 10:23 AM, Adrien Monteleone 
> mailto:adrien.montele...@lusfiber.net>> 
> wrote:
> 
> Then I misunderstood some earlier discussions about the UI, at least with 
> respect to Linux. What toolkit is envisioned to be used? What layout 
> principles? Or are those questions so far in the future as to not be worth 
> spending time allowing room for?
> 
> Regards,
> Adrien
> 
>> On Sep 11, 2018, at 12:18 PM, John Ralls > > wrote:
>> 
>> 
>> 
>>> On Sep 11, 2018, at 10:09 AM, Adrien Monteleone 
>>> mailto:adrien.montele...@lusfiber.net>> 
>>> wrote:
>>> 
>>> 
>>> 
 On Sep 11, 2018, at 8:13 AM, David T. via gnucash-devel 
 mailto:gnucash-devel@gnucash.org>> wrote:
 
 In other words, unless there is a change in function, there is no need to 
 change the functional description. It seems to me that putting text that 
 doesn’t change into code is essentially a one-time process. Not 
 necessarily easy, but once completed, not particularly obtrusive. Putting 
 the functional description into code has the added benefit, perhaps, of 
 alerting developers to the fact that if they change a feature, the 
 description (right there in the code) needs an update as well.
>>> 
>>> While the principles might not change, or even the name/label of certain 
>>> buttons, the UI layout (where those buttons are, the fact that they are 
>>> buttons instead of menu entries, etc.) will very likely change as the Gnome 
>>> HIG is more faithfully implemented. But those code changes shouldn’t affect 
>>> anything generally in the Guide, and should auto update the context help if 
>>> it is drawn from the code itself. If not, then consider that attempts to 
>>> corral GnuCash within the confines of the Gnome HIG, will produce such 
>>> changes you’re thinking won’t happen.
>> 
>> Why do you think we're going to "more faithfully implement" the Gnome HIG? 
>> One of our long-term goals is to remove our Gnome dependencies. 
>> 
>> Regards,
>> John Ralls
> 




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

Re: [GNC-dev] Yet another documentation compiling oddity

[David T. via gnucash-devel]

Sure. I defer to you. I was merely trying to anticipate that removal of 
“index.html” in the guide would cause some disruption.

> On Sep 14, 2018, at 12:10 PM, John Ralls  wrote:
> 
> 
> 
>> On Sep 14, 2018, at 7:55 AM, David T. via gnucash-devel 
>> mailto:gnucash-devel@gnucash.org>> wrote:
>> 
>> Hello,
>> 
>> As I am toiling through the depths of the documentation generation process, 
>> I am struck by the fact that the base page of the Help is “help.html”, while 
>> the base page for the guide is “index.html”.
>> 
>> For consistency, I suggest naming the guide base page “guide.html”; 
>> moreover, I suggest having a simple “index.html” placed in the documentation 
>> root folder (for me, that will be gnucash-docs/build”):
>> 
>> 
>> 
>> 
>>  > alink="#FF”>
>>  
>>> class="application">GnuCash Documentation
>>  
>>  
>>
>>> class="application">GnuCash Help 
>> Manual
>>Context menu and system help for 
>> GnuCash. 
>>
>>
>>> class="application">GnuCash 
>> Tutorial and Concepts Guide
>>Tutorial and Concept Guide for GnuCash, 
>> which provides in depth descriptions.
>>
>>  
>> 
>> 
> 
> Not quite. Remember that the documentation build is written to create the 
> documentation part of the website. 
> 
> We should change the name of gnucash-guide/index.html, but we should also 
> insert an index.html into every directory that raises an error to prevent 
> direct browsing; user access should be via https://www.gnucash.org/docs.phtml 
>  only. The generation of those index.html 
> files could be separated from the actual build both to avoid slowing the 
> build and to allow documenters to navigate separately from the TOCs in their 
> own build products.
> 
> I don’t think anything would be gained by having convenience index.html files 
> in the container directories for documenter browsing.
> 
> Regards,
> John Ralls
> 

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

Re: [GNC-dev] Yet another documentation compiling oddity

[Adrien Monteleone]

> On Sep 14, 2018, at 11:10 AM, John Ralls  wrote:
> 
> 
> We should change the name of gnucash-guide/index.html, but we should also 
> insert an index.html into every directory that raises an error to prevent 
> direct browsing; user access should be via https://www.gnucash.org/docs.phtml 
>  only. 

By this do you mean you don’t want people to see the contents of the directory?

If that’s the case, you can accomplish that with an .htaccess directive as 
follows:

# disable directory browsing
Options All -Indexes

You shouldn’t need ‘dummy’ index.html files.

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

Re: [GNC-dev] Yet another documentation compiling oddity

[John Ralls]

> On Sep 14, 2018, at 7:55 AM, David T. via gnucash-devel 
>  wrote:
> 
> Hello,
> 
> As I am toiling through the depths of the documentation generation process, I 
> am struck by the fact that the base page of the Help is “help.html”, while 
> the base page for the guide is “index.html”.
> 
> For consistency, I suggest naming the guide base page “guide.html”; moreover, 
> I suggest having a simple “index.html” placed in the documentation root 
> folder (for me, that will be gnucash-docs/build”):
> 
> 
> 
> 
>   alink="#FF”>
>  
> class="application">GnuCash Documentation
>  
>  
> 
>  class="application">GnuCash Help 
> Manual
> Context menu and system help for 
> GnuCash. 
> 
> 
>  class="application">GnuCash 
> Tutorial and Concepts Guide
> Tutorial and Concept Guide for GnuCash, 
> which provides in depth descriptions.
> 
>  
> 
> 

Not quite. Remember that the documentation build is written to create the 
documentation part of the website. 

We should change the name of gnucash-guide/index.html, but we should also 
insert an index.html into every directory that raises an error to prevent 
direct browsing; user access should be via https://www.gnucash.org/docs.phtml 
 only. The generation of those index.html 
files could be separated from the actual build both to avoid slowing the build 
and to allow documenters to navigate separately from the TOCs in their own 
build products.

I don’t think anything would be gained by having convenience index.html files 
in the container directories for documenter browsing.

Regards,
John Ralls

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

Re: [GNC-dev] Documentation Build Oddity

[D via gnucash-devel]

Ok, ok. You win.

I surrender.

On September 14, 2018, at 11:57 AM, John Ralls  wrote:




On Sep 14, 2018, at 8:34 AM, Geert Janssens  wrote:


Op vrijdag 14 september 2018 17:13:44 CEST schreef John Ralls:

On Sep 14, 2018, at 7:38 AM, David T. via gnucash-devel  wrote:

On Sep 14, 2018, at 10:28 AM, Frank H. Ellenberger
 wrote:>> 
Am 14.09.18 um 15:57 schrieb David T. via gnucash-devel:

For fullest consistency, I would opt to have each of the formats placed
in their own folder, named for tehir format:

epub *
html
mobi *
pdf *


*: Why do you want to create a directory for one file?


“For fullest consistency”: if you’re going to put one format into a
folder, put every one in a folder.

But in the case of HTML there’s a good reason for the inconsistency. You’re
heading into hobgoblin territory.

(adding "gnucash-guide” is redundant, since the folder hierarchy already
separates help from guide)>> 

But both end on https://code.gnucash.org/docs/C/.
ISTR we had to name the xmls - for yelp and naming them
different depending on their output format would complicate the make
files.


My build folder hierarchy is:

build

\guide

  \C
  \de

[etc.]

\help

  \C
  \de

[etc.]

IOW, the guide and help have separate hierarchies in build. I have no
connection to code.gnucash.org, and have no knowledge as to how the
information is stored there. ISTM that the structures of build
environments should be consistent across systems.

Sure you do, it’s just indirect via GitHub.com.


While true I doubt this is what Frank was referring to. As I understood he was 
referring to the directory structure where the nightly documentation builds 
are uploaded. And to make this upload easier the built docs are structured the 
way they are.

And yes, this may be slightly confusing after a first build. However I believe 
adding directories for pdf, epub and mobi will not do much to improve the 
documentation process. It would mean you have to navigate one level deeper 
each time to find the relevant derived files. As someone sensitive to rsi, I'm 
not looking forward to that.
I do think it keeps the main directory more tidy by grouping all html files in 
a subdirectory as it is now.


It was David T., not Frank, but no matter.


That repository is echoed to http://www.gnucash.org/docs/v3/. Since there’s no 
index.html except in http://www.gnucash.org/docs/v3/*/gnucash-guide/ one may 
browse the directory listings except those. As you say, it’s the same as the 
build results to simplify copying from the build directory to 
gnucash-htdocs-docs, but that’s scripted and user access to the docs is 
generally via http://www.gnucash.org/docs.phtml so the actual layout of either 
the build directory or the website docs folder could change without much 
impact... but frankly I don’t see any reason to change them.


Regards,

John Ralls


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

Re: [GNC-dev] Documentation Build Oddity

[John Ralls]

> On Sep 14, 2018, at 8:34 AM, Geert Janssens  
> wrote:
> 
> Op vrijdag 14 september 2018 17:13:44 CEST schreef John Ralls:
>>> On Sep 14, 2018, at 7:38 AM, David T. via gnucash-devel  de...@gnucash.org> wrote:
 On Sep 14, 2018, at 10:28 AM, Frank H. Ellenberger
  wrote:>> 
 Am 14.09.18 um 15:57 schrieb David T. via gnucash-devel:
> For fullest consistency, I would opt to have each of the formats placed
> in their own folder, named for tehir format:
> 
> epub *
> html
> mobi *
> pdf *
 
 *: Why do you want to create a directory for one file?
>>> 
>>> “For fullest consistency”: if you’re going to put one format into a
>>> folder, put every one in a folder.
>> But in the case of HTML there’s a good reason for the inconsistency. You’re
>> heading into hobgoblin territory.
> (adding "gnucash-guide” is redundant, since the folder hierarchy already
> separates help from guide)>> 
 But both end on https://code.gnucash.org/docs/C/.
 ISTR we had to name the xmls - for yelp and naming them
 different depending on their output format would complicate the make
 files.
>>> 
>>> My build folder hierarchy is:
>>> 
>>> build
>>> 
>>> \guide
>>> 
>>>   \C
>>>   \de
>>> 
>>> [etc.]
>>> 
>>> \help
>>> 
>>>   \C
>>>   \de
>>> 
>>> [etc.]
>>> 
>>> IOW, the guide and help have separate hierarchies in build. I have no
>>> connection to code.gnucash.org, and have no knowledge as to how the
>>> information is stored there. ISTM that the structures of build
>>> environments should be consistent across systems.
>> Sure you do, it’s just indirect via GitHub.com.
> 
> While true I doubt this is what Frank was referring to. As I understood he 
> was 
> referring to the directory structure where the nightly documentation builds 
> are uploaded. And to make this upload easier the built docs are structured 
> the 
> way they are.
> 
> And yes, this may be slightly confusing after a first build. However I 
> believe 
> adding directories for pdf, epub and mobi will not do much to improve the 
> documentation process. It would mean you have to navigate one level deeper 
> each time to find the relevant derived files. As someone sensitive to rsi, 
> I'm 
> not looking forward to that.
> I do think it keeps the main directory more tidy by grouping all html files 
> in 
> a subdirectory as it is now.

It was David T., not Frank, but no matter.

That repository is echoed to http://www.gnucash.org/docs/v3/ 
. Since there’s no index.html except in 
http://www.gnucash.org/docs/v3/*/gnucash-guide/ 
 one may browse the directory 
listings except those. As you say, it’s the same as the build results to 
simplify copying from the build directory to gnucash-htdocs-docs, but that’s 
scripted and user access to the docs is generally via 
http://www.gnucash.org/docs.phtml  so the 
actual layout of either the build directory or the website docs folder could 
change without much impact... but frankly I don’t see any reason to change them.

Regards,
John Ralls

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

Re: [GNC-dev] Documentation Build Oddity

[Geert Janssens]

Op vrijdag 14 september 2018 17:13:44 CEST schreef John Ralls:
> > On Sep 14, 2018, at 7:38 AM, David T. via gnucash-devel  wrote:
> >> On Sep 14, 2018, at 10:28 AM, Frank H. Ellenberger
> >>  wrote:>> 
> >> Am 14.09.18 um 15:57 schrieb David T. via gnucash-devel:
> >>> For fullest consistency, I would opt to have each of the formats placed
> >>> in their own folder, named for tehir format:
> >>> 
> >>> epub *
> >>> html
> >>> mobi *
> >>> pdf *
> >> 
> >> *: Why do you want to create a directory for one file?
> > 
> > “For fullest consistency”: if you’re going to put one format into a
> > folder, put every one in a folder.
> But in the case of HTML there’s a good reason for the inconsistency. You’re
> heading into hobgoblin territory.
> >>> (adding "gnucash-guide” is redundant, since the folder hierarchy already
> >>> separates help from guide)>> 
> >> But both end on https://code.gnucash.org/docs/C/.
> >> ISTR we had to name the xmls - for yelp and naming them
> >> different depending on their output format would complicate the make
> >> files.
> > 
> > My build folder hierarchy is:
> > 
> > build
> > 
> >  \guide
> >  
> >\C
> >\de
> > 
> > [etc.]
> > 
> >  \help
> >  
> >\C
> >\de
> > 
> > [etc.]
> > 
> > IOW, the guide and help have separate hierarchies in build. I have no
> > connection to code.gnucash.org, and have no knowledge as to how the
> > information is stored there. ISTM that the structures of build
> > environments should be consistent across systems.
> Sure you do, it’s just indirect via GitHub.com.

While true I doubt this is what Frank was referring to. As I understood he was 
referring to the directory structure where the nightly documentation builds 
are uploaded. And to make this upload easier the built docs are structured the 
way they are.

And yes, this may be slightly confusing after a first build. However I believe 
adding directories for pdf, epub and mobi will not do much to improve the 
documentation process. It would mean you have to navigate one level deeper 
each time to find the relevant derived files. As someone sensitive to rsi, I'm 
not looking forward to that.
I do think it keeps the main directory more tidy by grouping all html files in 
a subdirectory as it is now.

Geert


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

Re: [GNC-dev] Documentation Build Oddity

[John Ralls]

> On Sep 14, 2018, at 7:38 AM, David T. via gnucash-devel 
>  wrote:
> 
> 
> 
>> On Sep 14, 2018, at 10:28 AM, Frank H. Ellenberger 
>>  wrote:
>> 
>> 
>> 
>> Am 14.09.18 um 15:57 schrieb David T. via gnucash-devel:
>>> For fullest consistency, I would opt to have each of the formats placed in 
>>> their own folder, named for tehir format:
>>> 
>>> epub *
>>> html
>>> mobi *
>>> pdf *
>> 
>> *: Why do you want to create a directory for one file?
> 
> “For fullest consistency”: if you’re going to put one format into a folder, 
> put every one in a folder. 

But in the case of HTML there’s a good reason for the inconsistency. You’re 
heading into hobgoblin territory.

> 
>> 
>>> 
>>> (adding "gnucash-guide” is redundant, since the folder hierarchy already 
>>> separates help from guide)
>> 
>> But both end on https://code.gnucash.org/docs/C/.
>> ISTR we had to name the xmls - for yelp and naming them
>> different depending on their output format would complicate the make files.
> 
> My build folder hierarchy is:
> 
> build
>  \guide
>\C
>\de
> [etc.]
>  \help
>\C
>\de
> [etc.]
> 
> IOW, the guide and help have separate hierarchies in build. I have no 
> connection to code.gnucash.org, and have no knowledge as to how the 
> information is stored there. ISTM that the structures of build environments 
> should be consistent across systems.

Sure you do, it’s just indirect via GitHub.com. If you want to see how the 
information is stored do a bare clone:
  git clone --bare https://github.com/gnucash/gnucash-docs.git 

You’ll see that it’s pretty similar to your gnucash-docs/.git. For a more 
detailed understanding, see 
https://git-scm.com/book/en/v2/Git-Internals-Plumbing-and-Porcelain 
.

Regards,
John Ralls

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

[GNC-dev] Yet another documentation compiling oddity

[David T. via gnucash-devel]

Hello,

As I am toiling through the depths of the documentation generation process, I 
am struck by the fact that the base page of the Help is “help.html”, while the 
base page for the guide is “index.html”.

For consistency, I suggest naming the guide base page “guide.html”; moreover, I 
suggest having a simple “index.html” placed in the documentation root folder 
(for me, that will be gnucash-docs/build”):




  GnuCash 
Documentation
  
  
  
  GnuCash Help 
Manual
  Context menu and system help for 
GnuCash. 
  
  
  GnuCash Tutorial 
and Concepts Guide
  Tutorial and Concept Guide for GnuCash, 
which provides in depth descriptions.
  
  


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

Re: [GNC-dev] Documentation Build Oddity

[David T. via gnucash-devel]

> On Sep 14, 2018, at 10:28 AM, Frank H. Ellenberger 
>  wrote:
> 
> 
> 
> Am 14.09.18 um 15:57 schrieb David T. via gnucash-devel:
>> For fullest consistency, I would opt to have each of the formats placed in 
>> their own folder, named for tehir format:
>> 
>> epub *
>> html
>> mobi *
>> pdf *
> 
> *: Why do you want to create a directory for one file?

“For fullest consistency”: if you’re going to put one format into a folder, put 
every one in a folder. 

> 
>> 
>> (adding "gnucash-guide” is redundant, since the folder hierarchy already 
>> separates help from guide)
> 
> But both end on https://code.gnucash.org/docs/C/.
> ISTR we had to name the xmls - for yelp and naming them
> different depending on their output format would complicate the make files.

My build folder hierarchy is:

build
  \guide
\C
\de
[etc.]
  \help
\C
\de
[etc.]

IOW, the guide and help have separate hierarchies in build. I have no 
connection to code.gnucash.org, and have no knowledge as to how the information 
is stored there. ISTM that the structures of build environments should be 
consistent across systems.

> 
> Regards
> Frank
> 

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

Re: [GNC-dev] Documentation Build Oddity

[Frank H. Ellenberger]

Am 14.09.18 um 15:57 schrieb David T. via gnucash-devel:
> For fullest consistency, I would opt to have each of the formats placed in 
> their own folder, named for tehir format:
> 
> epub *
> html
> mobi *
> pdf *

*: Why do you want to create a directory for one file?

> 
> (adding "gnucash-guide” is redundant, since the folder hierarchy already 
> separates help from guide)

But both end on https://code.gnucash.org/docs/C/.
ISTR we had to name the xmls - for yelp and naming them
different depending on their output format would complicate the make files.

Regards
Frank

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

Re: [GNC-dev] Issues with FOP - PDF generation

[David T. via gnucash-devel]

John,

> On Sep 14, 2018, at 10:11 AM, John Ralls  wrote:
> 
> 
> 
>> On Sep 14, 2018, at 4:49 AM, D via gnucash-devel  
>> wrote:
>> 
>> That seems odd; the install page at Apache says it's a java app, and 
>> installation consists of copying jar files. No mention of /usr/bin...
>> 
>> Unfortunately, MacOS is different. Maybe John has advice for me...
> 
> I build the docs for distribution on a Linux VM so I’ve never installed FOP 
> directly on MacOS. 
> 
> The catch is the invocation of FOP: The instructions on the page you gave 
> just copy jars to ~/Library/Java/Extensions and say to invoke it with 
>  java  java org.apache.fop.cli.Main -fo
> pdf.make wants to just say “fop” so you need a to arrange for that with a 
> two-line shell file
>  #!/bin/sh
>  java  java org.apache.fop.cli.Main -fo $@
> named fop and somewhere on the path.
> 
> Regards,
> John Ralls

Thanks for the info. I went the Brew route, which put the executable in 
/usr/local/bin for me.

David

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

Re: [GNC-dev] Documentation update problems

[David T. via gnucash-devel]

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 
) 
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 
>  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=revision=13215=12785
> 
> OTOH it was a major improvement of the readability.
> 
> Regards
> Frank
> 

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

Re: [GNC-dev] Issues with FOP - PDF generation

[John Ralls]

> On Sep 14, 2018, at 4:49 AM, D via gnucash-devel  
> wrote:
> 
> 
> 
> On September 14, 2018, at 1:59 AM, "Frank H. Ellenberger" 
>  wrote:
> 
>> 
>> Am 14.09.18 um 03:55 schrieb David T. via gnucash-devel:
>>> OK, so I thought it would be nice to look at the changes I am implementing 
>>> in the documentation in PDF format, since I am rather old school, and like 
>>> to see the changes in a print format.
>>> 
>>> I went to the wiki, and followed the new directions there to try to compile 
>>> pdf documentation. 
>> which page?
> 
> https://wiki.gnucash.org/wiki/Documentation_Update_Instructions#Prepare_The_Build_Directory
> 
> 
>>> First, I ran ./autogen.sh, and aside from numerous warnings about a 
>>> non-POSIX variable name, everything went well.
>>> 
>>> Next, I changed to build and ran ../configure, and buried in there is the 
>>> message:
>>> 
>>> configure: WARNING: fop not found. You will not be able to generate PDF 
>>> files.
>>> 
>>> Ah. The wiki didn’t mention anything about this;
>> Such dependencies are usually in a specific README.dependencies or
>> direct in the README[.md] file.
>>> a search online indicates that fop refers to Apache FOP, and I followed 
>>> directions at http://www.working-software.com/node/18 
>>> ; to copy the various jar files 
>>> into ~/Library/Java/Extensions
>> Strange, I had only to install a package xmlgraphics-fop, but Macos
>> might behave different.
>> Result of 'which fop' returns a usable path like "/usr/bin/fop"?I
> 
> That seems odd; the install page at Apache says it's a java app, and 
> installation consists of copying jar files. No mention of /usr/bin...
> 
> Unfortunately, MacOS is different. Maybe John has advice for me...

I build the docs for distribution on a Linux VM so I’ve never installed FOP 
directly on MacOS. 

The catch is the invocation of FOP: The instructions on the page you gave just 
copy jars to ~/Library/Java/Extensions and say to invoke it with 
  java  java org.apache.fop.cli.Main -fo
pdf.make wants to just say “fop” so you need a to arrange for that with a 
two-line shell file
  #!/bin/sh
  java  java org.apache.fop.cli.Main -fo $@
named fop and somewhere on the path.

Regards,
John Ralls


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

Re: [GNC-dev] Documentation Build Oddity

[David T. via gnucash-devel]

Geert,

> On Sep 14, 2018, at 3:17 AM, Geert Janssens  
> wrote:
> This was done to be able to separate html output from the other formats.
> 
> pdf, ebub and mobi all output one single file. html outputs a whole series of 
> files. Putting those in their own directory creates one entry point per 
> format 
> in the language directory.
> 
> Granted it could have been "gnucash-guide.html" for even more consistency.

For fullest consistency, I would opt to have each of the formats placed in 
their own folder, named for tehir format:

epub
html
mobi
pdf

(adding "gnucash-guide” is redundant, since the folder hierarchy already 
separates help from guide)

> Geert
> 
> 

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

Re: [GNC-dev] Issues with FOP - PDF generation

[David T. via gnucash-devel]

I saw that option before, but having gone the Fink route in the past, I had 
hoped not to incur the overhead (both computing and psychic) that those tools 
impose.

I bit the bullet and gave Brew a try. It wasn’t difficult at all, and fop now 
works. Thanks for reminding me.

David

> On Sep 14, 2018, at 9:31 AM, Adrien Monteleone 
>  wrote:
> 
> David,
> 
> fop is available via Homebrew for Mac. I don’t use Fink or MacPorts so can’t 
> speak for them.
> 
> Perhaps that route will prove fruitful.
> 
> Regards,
> Adrien

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

Re: [GNC-dev] Issues with FOP - PDF generation

[Adrien Monteleone]

David,

fop is available via Homebrew for Mac. I don’t use Fink or MacPorts so can’t 
speak for them.

Perhaps that route will prove fruitful.

Regards,
Adrien

> On Sep 14, 2018, at 6:49 AM, D via gnucash-devel  
> wrote:
> 
> 
> 
> On September 14, 2018, at 1:59 AM, "Frank H. Ellenberger" 
>  wrote:
> 
>> 
>> Am 14.09.18 um 03:55 schrieb David T. via gnucash-devel:
>>> OK, so I thought it would be nice to look at the changes I am implementing 
>>> in the documentation in PDF format, since I am rather old school, and like 
>>> to see the changes in a print format.
>>> 
>>> I went to the wiki, and followed the new directions there to try to compile 
>>> pdf documentation. 
>> which page?
> 
> https://wiki.gnucash.org/wiki/Documentation_Update_Instructions#Prepare_The_Build_Directory
> 
> 
>>> First, I ran ./autogen.sh, and aside from numerous warnings about a 
>>> non-POSIX variable name, everything went well.
>>> 
>>> Next, I changed to build and ran ../configure, and buried in there is the 
>>> message:
>>> 
>>> configure: WARNING: fop not found. You will not be able to generate PDF 
>>> files.
>>> 
>>> Ah. The wiki didn’t mention anything about this;
>> Such dependencies are usually in a specific README.dependencies or
>> direct in the README[.md] file.
>>> a search online indicates that fop refers to Apache FOP, and I followed 
>>> directions at http://www.working-software.com/node/18 
>>> ; to copy the various jar files 
>>> into ~/Library/Java/Extensions
>> Strange, I had only to install a package xmlgraphics-fop, but Macos
>> might behave different.
>> Result of 'which fop' returns a usable path like "/usr/bin/fop"?I
> 
> That seems odd; the install page at Apache says it's a java app, and 
> installation consists of copying jar files. No mention of /usr/bin...
> 
> Unfortunately, MacOS is different. Maybe John has advice for me...
> 
>> Hope this helps a few steps further.
>> Frank
> 
> David
> ___
> 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] Issues with FOP - PDF generation

[D via gnucash-devel]

On September 14, 2018, at 1:59 AM, "Frank H. Ellenberger" 
 wrote:

>
>Am 14.09.18 um 03:55 schrieb David T. via gnucash-devel:
>> OK, so I thought it would be nice to look at the changes I am implementing 
>> in the documentation in PDF format, since I am rather old school, and like 
>> to see the changes in a print format.
>> 
>> I went to the wiki, and followed the new directions there to try to compile 
>> pdf documentation. 
>which page?

https://wiki.gnucash.org/wiki/Documentation_Update_Instructions#Prepare_The_Build_Directory


>> First, I ran ./autogen.sh, and aside from numerous warnings about a 
>> non-POSIX variable name, everything went well.
>> 
>> Next, I changed to build and ran ../configure, and buried in there is the 
>> message:
>> 
>> configure: WARNING: fop not found. You will not be able to generate PDF 
>> files.
>> 
>> Ah. The wiki didn’t mention anything about this;
>Such dependencies are usually in a specific README.dependencies or
>direct in the README[.md] file.
>> a search online indicates that fop refers to Apache FOP, and I followed 
>> directions at http://www.working-software.com/node/18 
>> ; to copy the various jar files 
>> into ~/Library/Java/Extensions
>Strange, I had only to install a package xmlgraphics-fop, but Macos
>might behave different.
>Result of 'which fop' returns a usable path like "/usr/bin/fop"?I

That seems odd; the install page at Apache says it's a java app, and 
installation consists of copying jar files. No mention of /usr/bin...

Unfortunately, MacOS is different. Maybe John has advice for me...

>Hope this helps a few steps further.
>Frank

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

Re: [GNC-dev] Documentation Build Oddity

[Geert Janssens]

Op vrijdag 14 september 2018 04:05:14 CEST schreef David T. via gnucash-devel:
> Hello,
> 
> In trying to deal with compiling the documentation, I have been trying to
> use the newer “make” methods for building the html docs. I am wondering why
> these commands create the output in a new directory within the language
> trees—respectively, “gnucash-guide” and "gnucash-help”. I don’t see the
> need for another layer of folders in this system, and wonder whether the
> output could simply be put in the language folders directly.
> 
This was done to be able to separate html output from the other formats.

pdf, ebub and mobi all output one single file. html outputs a whole series of 
files. Putting those in their own directory creates one entry point per format 
in the language directory.

Granted it could have been "gnucash-guide.html" for even more consistency.

Geert


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

[GNC-dev] Issues with FOP - PDF generation

[Frank H. Ellenberger]

Am 14.09.18 um 03:55 schrieb David T. via gnucash-devel:
> OK, so I thought it would be nice to look at the changes I am implementing in 
> the documentation in PDF format, since I am rather old school, and like to 
> see the changes in a print format.
> 
> I went to the wiki, and followed the new directions there to try to compile 
> pdf documentation. 

which page?

> First, I ran ./autogen.sh, and aside from numerous warnings about a non-POSIX 
> variable name, everything went well.
> 
> Next, I changed to build and ran ../configure, and buried in there is the 
> message:
> 
> configure: WARNING: fop not found. You will not be able to generate PDF files.
> 
> Ah. The wiki didn’t mention anything about this;

Such dependencies are usually in a specific README.dependencies or
direct in the README[.md] file.

> a search online indicates that fop refers to Apache FOP, and I followed 
> directions at http://www.working-software.com/node/18 
>  to copy the various jar files into 
> ~/Library/Java/Extensions

Strange, I had only to install a package xmlgraphics-fop, but Macos
might behave different.

Result of 'which fop' returns a usable path like "/usr/bin/fop"?
Then it is time to rerun configure in your build directory, which will
add the path to the makefiles.

> Issuing “make pdf” however, yielded:
> Making pdf in C
> fo 'gnucash-guide.fo' -pdf 'gnucash-guide.pdf> make[1]: fo: No such file or 
> directory
> make[1]: [gnucash-guide.pdf] Error 1 (ignored)

My output for branch maint, started in the root of my build directoryy:
> make pdf
Making pdf in help
make[1]: Verzeichnis „/home/frank/git/gnucash-docs/build/help“ wird betreten
Making pdf in C
make[2]: Verzeichnis „/home/frank/git/gnucash-docs/build/help/C“ wird
betreten
/usr/bin/xsltproc  --stringparam paper.type A4 -o 'gnucash-help.fo'
--stringparam fop1.extensions 1
/home/frank/git/gnucash-docs/xsl/1.75.2/fo/docbook.xsl
'/home/frank/git/gnucash-docs/help/C/gnucash-help.xml'
Making portrait pages on A4 paper (210mmx297mm)
/usr/bin/fop  -fo 'gnucash-help.fo' -pdf 'gnucash-help.pdf'
Sep 14, 2018 7:38:26 AM org.apache.fop.apps.FopConfParser configure
INFORMATION: Default page-height set to: 11.00in
Sep 14, 2018 7:38:26 AM org.apache.fop.apps.FopConfParser configure
INFORMATION: Default page-width set to: 8.50in
Sep 14, 2018 7:38:27 AM org.apache.fop.apps.FOUserAgent processEvent
WARNUNG: Unable to load font file:
file:/usr/share/fonts/texlive-avantgar/uagdo8a.pfb. Reason:
java.io.FileNotFoundException: Neither an AFM nor a PFM file was found
for file:/usr/share/fonts/texlive-avantgar/uagdo8a.pfb

So I need to reinstall a few fonts...

> This is repeated for each of the language trees. Digging around on the Apache 
> FOP pages led me down some scenic paths, but nothing seemed to shed light on 
> the problem.
> 
> Suggestions welcome.
> 
> David
> 

Hope this helps a few steps further.
Frank

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