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

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] 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] 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] Documentation Build Oddity

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

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