[GNC-dev] Yet another documentation compiling oddity

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

[GNC-dev] Yet another documentation compiling oddity

GnuCash - Dev mailing list
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>
_______________________________________________
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] Yet another documentation compiling oddity

John Ralls-2


> On Sep 14, 2018, at 7:55 AM, David T. via gnucash-devel <[hidden email]> 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

_______________________________________________
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] Yet another documentation compiling oddity

Adrien Monteleone-2


> On Sep 14, 2018, at 11:10 AM, John Ralls <[hidden email]> wrote:
>
>
> 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.

By this do you mean you don’t want people to see the contents of the directory?

If that’s the case, you can accomplish that with an .htaccess directive as follows:

# disable directory browsing
Options All -Indexes

You shouldn’t need ‘dummy’ index.html files.

Regards,
Adrien
_______________________________________________
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] Yet another documentation compiling oddity

GnuCash - Dev mailing list
In reply to this post by John Ralls-2
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 <[hidden email]> wrote:
>
>
>
>> On Sep 14, 2018, at 7:55 AM, David T. via gnucash-devel <[hidden email] <mailto:[hidden email]>> 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
>

_______________________________________________
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] Yet another documentation compiling oddity

John Ralls-2
In reply to this post by Adrien Monteleone-2


> On Sep 14, 2018, at 9:24 AM, Adrien Monteleone <[hidden email]> wrote:
>
>
>
>> On Sep 14, 2018, at 11:10 AM, John Ralls <[hidden email]> wrote:
>>
>>
>> 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.
>
> By this do you mean you don’t want people to see the contents of the directory?
>
> If that’s the case, you can accomplish that with an .htaccess directive as follows:
>
> # disable directory browsing
> Options All -Indexes
>
> You shouldn’t need ‘dummy’ index.html files.

It's my understanding that that's less than perfect. It's standard practice in the the CMS world to put poisoned index.html files in directories where you don't want browsers poking their noses.

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] Yet another documentation compiling oddity

Adrien Monteleone-2
Interesting. I’ll investigate. I’ve never had an issue that I’m aware of. If the server won’t even let you get there due to the directive...?

Regards,
Adrien

> On Sep 14, 2018, at 5:38 PM, John Ralls <[hidden email]> wrote:
>
> It's my understanding that that's less than perfect. It's standard practice in the the CMS world to put poisoned index.html files in directories where you don't want browsers poking their noses.
>
> 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] Yet another documentation compiling oddity

Geert Janssens-4
In reply to this post by GnuCash - Dev mailing list
Op vrijdag 14 september 2018 16:55:33 CEST schreef David T. via gnucash-devel:
> 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”;

If we change it for consistency I'm inclined to rename both to index.html. That will help web
servers to open the correct start page if users omit it and would be consistent with how
websites are generally set up.

It's been a long while since last time I was focusing on the documentation sources. I remember
noticing the inconsistency back then as well. But for some reason I had decided not to change it.
I know that if we do so we'll have to make adjustments to the integrated help and guide display
on Macos, to the build system for gnucash on Windows, for the nightly build script for
documentation and for the website. Perhaps I considered that too much effort back then. I'm
less worried about that now and I like consistency so I'll see if I can coordinate this change with
Derek.

> moreover, I suggest having a simple “index.html” placed in the
> documentation root folder (for me, that will be gnucash-docs/build”):

I actually like this idea. It would give a local webpage to quickly open all available
documentation in the current build environment.

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] Yet another documentation compiling oddity

John Ralls-2
In reply to this post by Adrien Monteleone-2
If an attacker guesses the path a -Indexes directive won’t stop him from requesting the directory from the server. It should return a 403 if there’s no index.html, but perhaps there are servers out there that fail, or perhaps the web design folks think that a blank page is better than a 403.

Of course it’s also possible that the practice got going before -Indexes was added and never went away, or that since .htaccess is an Apache thing it’s not sufficiently general (nginx seems to require per-directory config of its autoindex module in its config file, no idea about IIS).

Regards,
John Ralls


> On Sep 14, 2018, at 9:13 PM, Adrien Monteleone <[hidden email]> wrote:
>
> Interesting. I’ll investigate. I’ve never had an issue that I’m aware of. If the server won’t even let you get there due to the directive...?
>
> Regards,
> Adrien
>
>> On Sep 14, 2018, at 5:38 PM, John Ralls <[hidden email]> wrote:
>>
>> It's my understanding that that's less than perfect. It's standard practice in the the CMS world to put poisoned index.html files in directories where you don't want browsers poking their noses.
>>
>> Regards,
>> John Ralls
>
>
> _______________________________________________
> gnucash-devel mailing list
> [hidden email]
> https://lists.gnucash.org/mailman/listinfo/gnucash-devel

_______________________________________________
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] Yet another documentation compiling oddity

Adrien Monteleone-2
Thanks for the background. I wasn’t thinking of the case of other types of servers, as I so far only deal with Apache.

> On Sep 15, 2018, at 9:28 AM, John Ralls <[hidden email]> wrote:
>
> If an attacker guesses the path a -Indexes directive won’t stop him from requesting the directory from the server. It should return a 403 if there’s no index.html, but perhaps there are servers out there that fail, or perhaps the web design folks think that a blank page is better than a 403.
>
> Of course it’s also possible that the practice got going before -Indexes was added and never went away, or that since .htaccess is an Apache thing it’s not sufficiently general (nginx seems to require per-directory config of its autoindex module in its config file, no idea about IIS).
>
> Regards,
> John Ralls
>
>
>> On Sep 14, 2018, at 9:13 PM, Adrien Monteleone <[hidden email]> wrote:
>>
>> Interesting. I’ll investigate. I’ve never had an issue that I’m aware of. If the server won’t even let you get there due to the directive...?
>>
>> Regards,
>> Adrien
>>
>>> On Sep 14, 2018, at 5:38 PM, John Ralls <[hidden email]> wrote:
>>>
>>> It's my understanding that that's less than perfect. It's standard practice in the the CMS world to put poisoned index.html files in directories where you don't want browsers poking their noses.
>>>
>>> Regards,
>>> John Ralls
>>
>>
>> _______________________________________________
>> gnucash-devel mailing list
>> [hidden email]
>> https://lists.gnucash.org/mailman/listinfo/gnucash-devel
>
>


_______________________________________________
gnucash-devel mailing list
[hidden email]
https://lists.gnucash.org/mailman/listinfo/gnucash-devel