Iconv.html and iconv.html

Iconv.html and iconv.html

[Torbjorn SVENSSON]

Hello,

I have been building a toolchain for the arm-none-eabi target using a 
rather recent snapshot of newlib. While building the html documentation, 
I noticed that there will be generated the two files named Iconv.html 
and iconv.html.
While this works fine for case sensitive file systems, it's obvious that 
this will not have the desired outcome on a case-insensitive file 
system, such as on Windows system.

The Iconv.html file contains the chapter description and the iconv.html 
file contains the description of the iconv-function.

Can someone, with the knowledge of how these filenames are generated, 
change one of them so that the filenames differ on a case insensitive 
file system?

Kind regards,
Torbjörn

Re: Iconv.html and iconv.html

[Mike Frysinger]

[-- Attachment #1: Type: text/plain, Size: 1742 bytes --]

On 02 Dec 2022 17:06, Torbjorn SVENSSON wrote:
> I have been building a toolchain for the arm-none-eabi target using a 
> rather recent snapshot of newlib. While building the html documentation, 
> I noticed that there will be generated the two files named Iconv.html 
> and iconv.html.
> While this works fine for case sensitive file systems, it's obvious that 
> this will not have the desired outcome on a case-insensitive file 
> system, such as on Windows system.
> 
> The Iconv.html file contains the chapter description and the iconv.html 
> file contains the description of the iconv-function.
> 
> Can someone, with the knowledge of how these filenames are generated, 
> change one of them so that the filenames differ on a case insensitive 
> file system?

the naming is straightforward -- the @node attribute is turned directly into
the filename.  we use @node Iconv for the chapter and @node iconv for the C
function APIs.  so the fix is to change one of them.

the sub-areas have a 1-to-1 mapping to the chapter (e.g. stdio/->Stdio,
iconv/->Iconv, etc...).  the generated APIs similarly map source file
names to the chapter (e.g. iconv.c->iconv, strncmp.c->strncmp).  but they
can map any number of functions inside those source files, and we might
rename them as makes sense in general for our organization.  so i'm more
inclined to change the generated API chapters, and do it across the board
instead of a one-off for iconv.c.

anyone want to bikeshed the naming convention ?  gen_xxx ?  src_xxx ?
there doesn't seem to be a standard here in the GNU toolchain space that
i can see.  bfd/ has a conflict, but they just do a one-off rename with
bfd.texi->bfdt.texi for the makedoc output.
-mike

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: Iconv.html and iconv.html

[Torbjorn SVENSSON]

Hi Mike,

On 2022-12-09 17:29, Mike Frysinger wrote:
> On 02 Dec 2022 17:06, Torbjorn SVENSSON wrote:
>> I have been building a toolchain for the arm-none-eabi target using a
>> rather recent snapshot of newlib. While building the html documentation,
>> I noticed that there will be generated the two files named Iconv.html
>> and iconv.html.
>> While this works fine for case sensitive file systems, it's obvious that
>> this will not have the desired outcome on a case-insensitive file
>> system, such as on Windows system.
>>
>> The Iconv.html file contains the chapter description and the iconv.html
>> file contains the description of the iconv-function.
>>
>> Can someone, with the knowledge of how these filenames are generated,
>> change one of them so that the filenames differ on a case insensitive
>> file system?
> 
> the naming is straightforward -- the @node attribute is turned directly into
> the filename.  we use @node Iconv for the chapter and @node iconv for the C
> function APIs.  so the fix is to change one of them.
> 
> the sub-areas have a 1-to-1 mapping to the chapter (e.g. stdio/->Stdio,
> iconv/->Iconv, etc...).  the generated APIs similarly map source file
> names to the chapter (e.g. iconv.c->iconv, strncmp.c->strncmp).  but they
> can map any number of functions inside those source files, and we might
> rename them as makes sense in general for our organization.  so i'm more
> inclined to change the generated API chapters, and do it across the board
> instead of a one-off for iconv.c.
> 
> anyone want to bikeshed the naming convention ?  gen_xxx ?  src_xxx ?
> there doesn't seem to be a standard here in the GNU toolchain space that
> i can see.  bfd/ has a conflict, but they just do a one-off rename with
> bfd.texi->bfdt.texi for the makedoc output.


To me, I think "gen_xxx" is preferred in that case.
I think GDB has another of those conflicts (that is still to be solved) 
with qMemTags vs QMemTags.

Kind regards,
Torbjörn

Re: Iconv.html and iconv.html

[Mike Frysinger]

[-- Attachment #1: Type: text/plain, Size: 1907 bytes --]

On 10 Dec 2022 01:29, Mike Frysinger wrote:
> On 02 Dec 2022 17:06, Torbjorn SVENSSON wrote:
> > I have been building a toolchain for the arm-none-eabi target using a 
> > rather recent snapshot of newlib. While building the html documentation, 
> > I noticed that there will be generated the two files named Iconv.html 
> > and iconv.html.
> > While this works fine for case sensitive file systems, it's obvious that 
> > this will not have the desired outcome on a case-insensitive file 
> > system, such as on Windows system.
> > 
> > The Iconv.html file contains the chapter description and the iconv.html 
> > file contains the description of the iconv-function.
> > 
> > Can someone, with the knowledge of how these filenames are generated, 
> > change one of them so that the filenames differ on a case insensitive 
> > file system?
> 
> the naming is straightforward -- the @node attribute is turned directly into
> the filename.  we use @node Iconv for the chapter and @node iconv for the C
> function APIs.  so the fix is to change one of them.
> 
> the sub-areas have a 1-to-1 mapping to the chapter (e.g. stdio/->Stdio,
> iconv/->Iconv, etc...).

i took another look at this ... my initial dataset coincidentally aligned,
but looking at all of them, it seems we already aren't standardized.
ctype/ctype.tex Ctype
iconv/iconv.tex Iconv
locale/locale.tex Locale
misc/misc.tex Misc
posix/posix.tex Posix
reent/reent.tex Reentrancy
signal/signal.tex Signals
ssp/ssp.tex Overflow Protection
stdio64/stdio64.tex Stdio64
stdio/stdio.tex Stdio
stdlib/stdlib.tex Stdlib
string/strings.tex Strings
string/wcstrings.tex Wchar strings
time/time.tex Timefns

it's common for @node & @chapter to be aligned, so looking at iconv.tex:
@node Iconv
@chapter Encoding conversions (@file{iconv.h})

so changing @node to "Encoding conversions" seems pretty easy.
-mike

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

[PATCH] newlib: info: tweak iconv node to avoid collisions

[Mike Frysinger]

We have "Iconv" and "iconv" nodes which generates Iconv.html and
iconv.html files.  On a case-insensitive filesystem, these collide.
Rename the "Iconv" node to match the chapter name that it's already
using to avoid the issue.
---
 newlib/libc/iconv/iconv.tex | 2 +-
 newlib/libc/libc.texi       | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/newlib/libc/iconv/iconv.tex b/newlib/libc/iconv/iconv.tex
index 42d04c0b616f..5b1f7518a4fe 100644
--- a/newlib/libc/iconv/iconv.tex
+++ b/newlib/libc/iconv/iconv.tex
@@ -1,4 +1,4 @@
-@node Iconv
+@node Encoding conversions
 @chapter Encoding conversions (@file{iconv.h})
 
 This chapter describes the Newlib iconv library.
diff --git a/newlib/libc/libc.texi b/newlib/libc/libc.texi
index d217d8118277..72328e148bf6 100644
--- a/newlib/libc/libc.texi
+++ b/newlib/libc/libc.texi
@@ -151,7 +151,7 @@ into another language, under the above conditions for modified versions.
 * Posix::
 * Syscalls::
 * Arglists::
-* Iconv::
+* Encoding conversions::
 * Overflow Protection::
 
 * Document Index::
-- 
2.38.1

Re: [PATCH] newlib: info: tweak iconv node to avoid collisions

[Jeff Johnston]

[-- Attachment #1: Type: text/plain, Size: 1234 bytes --]

LGTM.

-- Jeff J.

On Sat, Dec 10, 2022 at 3:30 AM Mike Frysinger <vapier@gentoo.org> wrote:

> We have "Iconv" and "iconv" nodes which generates Iconv.html and
> iconv.html files.  On a case-insensitive filesystem, these collide.
> Rename the "Iconv" node to match the chapter name that it's already
> using to avoid the issue.
> ---
>  newlib/libc/iconv/iconv.tex | 2 +-
>  newlib/libc/libc.texi       | 2 +-
>  2 files changed, 2 insertions(+), 2 deletions(-)
>
> diff --git a/newlib/libc/iconv/iconv.tex b/newlib/libc/iconv/iconv.tex
> index 42d04c0b616f..5b1f7518a4fe 100644
> --- a/newlib/libc/iconv/iconv.tex
> +++ b/newlib/libc/iconv/iconv.tex
> @@ -1,4 +1,4 @@
> -@node Iconv
> +@node Encoding conversions
>  @chapter Encoding conversions (@file{iconv.h})
>
>  This chapter describes the Newlib iconv library.
> diff --git a/newlib/libc/libc.texi b/newlib/libc/libc.texi
> index d217d8118277..72328e148bf6 100644
> --- a/newlib/libc/libc.texi
> +++ b/newlib/libc/libc.texi
> @@ -151,7 +151,7 @@ into another language, under the above conditions for
> modified versions.
>  * Posix::
>  * Syscalls::
>  * Arglists::
> -* Iconv::
> +* Encoding conversions::
>  * Overflow Protection::
>
>  * Document Index::
> --
> 2.38.1
>
>