[GNC-dev] Documentation Build Oddity

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

[GNC-dev] Documentation Build Oddity

GnuCash - Dev mailing list
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
[hidden email]
https://lists.gnucash.org/mailman/listinfo/gnucash-devel
Reply | Threaded
Open this post in threaded view
|

Re: [GNC-dev] Documentation Build Oddity

Geert Janssens-4
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
[hidden email]
https://lists.gnucash.org/mailman/listinfo/gnucash-devel
Reply | Threaded
Open this post in threaded view
|

Re: [GNC-dev] Documentation Build Oddity

GnuCash - Dev mailing list
Geert,

> On Sep 14, 2018, at 3:17 AM, Geert Janssens <[hidden email]> 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
[hidden email]
https://lists.gnucash.org/mailman/listinfo/gnucash-devel
Reply | Threaded
Open this post in threaded view
|

Re: [GNC-dev] Documentation Build Oddity

Frank H. Ellenberger-3


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 <App>-<DocType> for yelp and naming them
different depending on their output format would complicate the make files.

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

GnuCash - Dev mailing list


> On Sep 14, 2018, at 10:28 AM, Frank H. Ellenberger <[hidden email]> 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 <App>-<DocType> 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
[hidden email]
https://lists.gnucash.org/mailman/listinfo/gnucash-devel
Reply | Threaded
Open this post in threaded view
|

Re: [GNC-dev] Documentation Build Oddity

John Ralls-2


> On Sep 14, 2018, at 7:38 AM, David T. via gnucash-devel <[hidden email]> wrote:
>
>
>
>> On Sep 14, 2018, at 10:28 AM, Frank H. Ellenberger <[hidden email]> 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 <App>-<DocType> 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 <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 <https://git-scm.com/book/en/v2/Git-Internals-Plumbing-and-Porcelain>.

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

Geert Janssens-4
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 <gnucash-
[hidden email]> wrote:

> >> On Sep 14, 2018, at 10:28 AM, Frank H. Ellenberger
> >> <[hidden email]> 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 <App>-<DocType> 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
[hidden email]
https://lists.gnucash.org/mailman/listinfo/gnucash-devel
Reply | Threaded
Open this post in threaded view
|

Re: [GNC-dev] Documentation Build Oddity

John Ralls-2


> On Sep 14, 2018, at 8:34 AM, Geert Janssens <[hidden email]> 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 <gnucash-
> [hidden email]> wrote:
>>>> On Sep 14, 2018, at 10:28 AM, Frank H. Ellenberger
>>>> <[hidden email]> 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 <App>-<DocType> 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/ <http://www.gnucash.org/docs/v3/>. Since there’s no index.html except in http://www.gnucash.org/docs/v3/*/gnucash-guide/ <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 <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
[hidden email]
https://lists.gnucash.org/mailman/listinfo/gnucash-devel
Reply | Threaded
Open this post in threaded view
|

Re: [GNC-dev] Documentation Build Oddity

GnuCash - Dev mailing list
In reply to this post by GnuCash - Dev mailing list
Ok, ok. You win.

I surrender.

On September 14, 2018, at 11:57 AM, John Ralls <[hidden email]> wrote:




On Sep 14, 2018, at 8:34 AM, Geert Janssens <[hidden email]> 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 <gnucash-

[hidden email]> wrote:

On Sep 14, 2018, at 10:28 AM, Frank H. Ellenberger
<[hidden email]> 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 <App>-<DocType> 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
[hidden email]
https://lists.gnucash.org/mailman/listinfo/gnucash-devel