[GNC-dev] Yet another documentation compiling oddity

Fri Sep 14 12:36:26 EDT 2018

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 <jralls at ceridwen.us> wrote:
> 
> 
> 
>> On Sep 14, 2018, at 7:55 AM, David T. via gnucash-devel <gnucash-devel at gnucash.org <mailto:gnucash-devel at 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”):
>> 
>> 
>> <html>
>> <head>
>>  <meta http-equiv="Content-Type" content="text/html; charset=UTF-8”>
>>  <title>GnuCash Documentation</title>
>>  <meta name="generator" content="DocBook XSL Stylesheets V1.75.2”>
>> </head>
>> <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF”>
>>  <div>
>>    <h1 class="title"><strong class="application"><code>GnuCash</code></strong> Documentation</h1>
>>  </div>
>>  <table width="100%" summary="Documentation List">
>> 	  <tr>
>> 		  <td width="40%" align="left"><strong xmlns="" class="application"><a href="help/C/help.html"><code>GnuCash</code> Help Manual</a></strong></td>
>> 		  <td>Context menu and system help for <code>GnuCash</code>.</td> 
>> 	  </tr>
>> 	  <tr>
>> 		  <td width="40%" align="left"><strong xmlns="" class="application"><a href="guide/C/guide.html"><code>GnuCash</code> Tutorial and Concepts Guide</a></strong></td>
>> 		  <td>Tutorial and Concept Guide for <code>GnuCash</code>, which provides in depth descriptions.</td>
>> 	  </tr>
>>  </table>
>> </body>
>> </html>
> 
> 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 <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
> 