emacs manuals: make docs (html) issue with the index.html output

emacs manuals: make docs (html) issue with the index.html output

[Jean-Christophe Helary]

I am not sure whether this is an emacs "make" issue or a texinfo issue so I am sending this report to the 2 lists.

When running "make docs" to produce the emacs manuals HTML sets with the following options:

HTML_OPTS = --split=chapter --html

There are issues with the ToC files and index files in

1) the elisp reference set
2) the lisp intro set

In both cases, the issue seems to be that the ToC is output as "index.html#SEC_Contents" and is then overwritten by the index which is output as "Index.html" (notice the change in case).

The navigation HTML reads:

[<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Index.html" title="Index" rel="index">Index</a>]

In the [misc] section, the following manuals show the same faulty behavior:

- auth
- dbus
- ediff
- emacs-mime
- ert
- eudc
- flymake
- forms
- gnus
- htmlfontify
- info
- message
- newsticker
- rcirc
- reftex
- sasl
- semantic
- ses
- sieve
- smtpmail
- speedbar
- srecode
- widget
- wisent

In the case of the Emacs manual, the links work since Emacs uses 5 different index files that are accordingly named differently:

[<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Key-Index.html" title="Index" rel="index">Index</a>]

The org-mode manual too has 4 indexes and works fine:

[<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Main-Index.html" title="Index" rel="index">Index</a>]


It looks like (I have not checked for all the manuals) when a manual only has 1 index it is output as Index.html and the ToC is output as index.html, but on case-insensitive systems (macOS) the files conflict and only the index is kept (presumably after overwriting the ToC).

Wouldn't it be more sensible to call the ToC just ToC.html so that it never conflicts with any concept index file?

-- 
Jean-Christophe Helary @brandelune
https://mac4translators.blogspot.com
https://sr.ht/~brandelune/omegat-as-a-book/

Re: emacs manuals: make docs (html) issue with the index.html output

[Gavin Smith]

On Tue, Oct 19, 2021 at 03:31:28PM +0900, Jean-Christophe Helary wrote:
> I am not sure whether this is an emacs "make" issue or a texinfo issue so I am sending this report to the 2 lists.
> 
> When running "make docs" to produce the emacs manuals HTML sets with the following options:
> 
> HTML_OPTS = --split=chapter --html
> 
> There are issues with the ToC files and index files in
> 
> 1) the elisp reference set
> 2) the lisp intro set
> 
> In both cases, the issue seems to be that the ToC is output as "index.html#SEC_Contents" and is then overwritten by the index which is output as "Index.html" (notice the change in case).
> 
> The navigation HTML reads:
> 
> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Index.html" title="Index" rel="index">Index</a>]

Can you link to an online manual where the problem occurs as I couldn't find
one (I checked three of the emacs manuals before giving up).

> It looks like (I have not checked for all the manuals) when a manual only has 1 index it is output as Index.html and the ToC is output as index.html, but on case-insensitive systems (macOS) the files conflict and only the index is kept (presumably after overwriting the ToC).

Have you actually tested this on macOS?

I haven't but I remember there was code in texi2any to deal with this exact
eventuality.

I haven't but I remember there was code in texi2any to deal with this exact
eventuality.  If there was a node called "index" then it would be output at
the bottom of index.html.

> Wouldn't it be more sensible to call the ToC just ToC.html so that it never conflicts with any concept index file?

For HTTP, index.html is a special name that is the file returned if
no filename component was present in the URL.

Re: emacs manuals: make docs (html) issue with the index.html output

[Jean-Christophe Helary]

>> When running "make docs" to produce the emacs manuals HTML sets with the following options:
>> 
>> HTML_OPTS = --split=chapter --html
>> 
>> There are issues with the ToC files and index files in
>> 
>> 1) the elisp reference set
>> 2) the lisp intro set
>> 
>> In both cases, the issue seems to be that the ToC is output as "index.html#SEC_Contents" and is then overwritten by the index which is output as "Index.html" (notice the change in case).
>> 
>> The navigation HTML reads:
>> 
>> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Index.html" title="Index" rel="index">Index</a>]
> 
> Can you link to an online manual where the problem occurs as I couldn't find
> one (I checked three of the emacs manuals before giving up).

https://doublet.jp/gnu/

https://doublet.jp/gnu/elisp/elisp.html/index.html

https://doublet.jp/gnu/lispintro/emacs-lisp-intro.html/index.html

>> It looks like (I have not checked for all the manuals) when a manual only has 1 index it is output as Index.html and the ToC is output as index.html, but on case-insensitive systems (macOS) the files conflict and only the index is kept (presumably after overwriting the ToC).
> 
> Have you actually tested this on macOS?

Yes. That's my machine.

> I haven't but I remember there was code in texi2any to deal with this exact
> eventuality.
> 
> I haven't but I remember there was code in texi2any to deal with this exact
> eventuality.  If there was a node called "index" then it would be output at
> the bottom of index.html.
> 
>> Wouldn't it be more sensible to call the ToC just ToC.html so that it never conflicts with any concept index file?
> 
> For HTTP, index.html is a special name that is the file returned if
> no filename component was present in the URL.

You're right. So that the other index that needs to be named in a different fashion.


-- 
Jean-Christophe Helary @brandelune
https://mac4translators.blogspot.com
https://sr.ht/~brandelune/omegat-as-a-book/

Re: emacs manuals: make docs (html) issue with the index.html output

[Eli Zaretskii]

> From: Jean-Christophe Helary <lists@traduction-libre.org>
> Date: Tue, 19 Oct 2021 15:31:28 +0900
> 
> I am not sure whether this is an emacs "make" issue or a texinfo issue so I am sending this report to the 2 lists.

It's a Texinfo issue.

Please in the future don't cross-post; instead, post to one list, and
if told to post to another, do it then.

Thanks.

Re: emacs manuals: make docs (html) issue with the index.html output

[Gavin Smith]

On Tue, Oct 19, 2021 at 08:30:59PM +0900, Jean-Christophe Helary wrote:
> >> When running "make docs" to produce the emacs manuals HTML sets with the following options:
> >> 
> >> HTML_OPTS = --split=chapter --html
> >> 
> >> There are issues with the ToC files and index files in
> >> 
> >> 1) the elisp reference set
> >> 2) the lisp intro set
> >> 
> >> In both cases, the issue seems to be that the ToC is output as "index.html#SEC_Contents" and is then overwritten by the index which is output as "Index.html" (notice the change in case).
> >> 
> >> The navigation HTML reads:
> >> 
> >> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Index.html" title="Index" rel="index">Index</a>]
> > 
> > Can you link to an online manual where the problem occurs as I couldn't find
> > one (I checked three of the emacs manuals before giving up).
> 
> https://doublet.jp/gnu/
> 
> https://doublet.jp/gnu/elisp/elisp.html/index.html
> 
> https://doublet.jp/gnu/lispintro/emacs-lisp-intro.html/index.html
> 
> >> It looks like (I have not checked for all the manuals) when a manual only has 1 index it is output as Index.html and the ToC is output as index.html, but on case-insensitive systems (macOS) the files conflict and only the index is kept (presumably after overwriting the ToC).
> > 
> > Have you actually tested this on macOS?
> 
> Yes. That's my machine.

I'm trying to catch up with Texinfo mail.

I saw the problem with the Top node not being present in the links you sent above.

There appears to be code to check a CASE_INSENSITIVE_FILENAMES configuration
value in Texinfo/Common.pm, now in set_tree_unit_file.  Could you try
building your manuals with texi2any -c CASE_INSENSITIVE_FILENAMES=1 and see
if that makes a difference?

Re: emacs manuals: make docs (html) issue with the index.html output

[Jean-Christophe Helary]

> On Dec 22, 2021, at 4:00, Gavin Smith <gavinsmith0123@gmail.com> wrote:
> 
> On Tue, Oct 19, 2021 at 08:30:59PM +0900, Jean-Christophe Helary wrote:
>>>> When running "make docs" to produce the emacs manuals HTML sets with the following options:
>>>> 
>>>> HTML_OPTS = --split=chapter --html
>>>> 
>>>> There are issues with the ToC files and index files in
>>>> 
>>>> 1) the elisp reference set
>>>> 2) the lisp intro set
>>>> 
>>>> In both cases, the issue seems to be that the ToC is output as "index.html#SEC_Contents" and is then overwritten by the index which is output as "Index.html" (notice the change in case).
>>>> 
>>>> The navigation HTML reads:
>>>> 
>>>> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Index.html" title="Index" rel="index">Index</a>]
>>> 
>>> Can you link to an online manual where the problem occurs as I couldn't find
>>> one (I checked three of the emacs manuals before giving up).
>> 
>> https://doublet.jp/gnu/
>> 
>> https://doublet.jp/gnu/elisp/elisp.html/index.html
>> 
>> https://doublet.jp/gnu/lispintro/emacs-lisp-intro.html/index.html
>> 
>>>> It looks like (I have not checked for all the manuals) when a manual only has 1 index it is output as Index.html and the ToC is output as index.html, but on case-insensitive systems (macOS) the files conflict and only the index is kept (presumably after overwriting the ToC).
>>> 
>>> Have you actually tested this on macOS?
>> 
>> Yes. That's my machine.
> 
> I'm trying to catch up with Texinfo mail.
> 
> I saw the problem with the Top node not being present in the links you sent above.
> 
> There appears to be code to check a CASE_INSENSITIVE_FILENAMES configuration
> value in Texinfo/Common.pm, now in set_tree_unit_file.  Could you try
> building your manuals with texi2any -c CASE_INSENSITIVE_FILENAMES=1 and see
> if that makes a difference?

Thank you Gavin for looking into this.

I've checked where the manuals creation process calls texi2any and failed to find anything. It looks like makeinfo is an alias to texi2any to what I did is add the option to the various makefiles:

for ex:

MAKEINFO = @MAKEINFO@
MAKEINFO_OPTS = --force --enable-encoding -I $(srcdir) -c CASE_INSENSITIVE_FILENAMES=1

checking right now it that works...

-- 
Jean-Christophe Helary @brandelune
https://mac4translators.blogspot.com
https://sr.ht/~brandelune/omegat-as-a-book/