[GNC-dev] Documentation Build Oddity

[John Ralls]

> On Sep 14, 2018, at 8:34 AM, Geert Janssens <geert.gnucash at kobaltwit.be> 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-
> devel at gnucash.org> wrote:
>>>> On Sep 14, 2018, at 10:28 AM, Frank H. Ellenberger
>>>> <frank.h.ellenberger at gmail.com> 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