[GNC-dev] Documentation Build Oddity

[D]

Ok, ok. You win.

I surrender.

On September 14, 2018, at 11:57 AM, John Ralls <jralls at ceridwen.us> wrote:




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