Online documentation revisions

Online documentation revisions

[Sam Edge]

Hi Corinna et al.

It's my first time here so apologies if I'm being thick.

Is there any way to see the online documentation for Newlib for a given 
release?

I often get lumbered with having to use older revisions (3.0.0!) that 
don't come with source or pre-built HTML or other documentation. (Yes, 
STM, I'm talking to you!)

Is there a way to see the state of the online docs at a given revision?

Cheers.

-- 
Sam Edge

Re: Online documentation revisions

[Brian Inglis]

On 2023-09-26 09:27, Sam Edge wrote:
> It's my first time here so apologies if I'm being thick.
> Is there any way to see the online documentation for Newlib for a given release?
> I often get lumbered with having to use older revisions (3.0.0!) that don't come 
> with source or pre-built HTML or other documentation. (Yes, STM, I'm talking to 
> you!)
> Is there a way to see the state of the online docs at a given revision?

Had a similar issue wanting to see libc docs for Cygwin builds.

Check out repo at that rev, configure into out of tree build and install dirs, 
then under e.g. build-3.0.0/newlib run to get into your e.g. 
install-3.0.0/usr/share/{info,man} dirs:

	$ make info man && make install info man

-- 
Take care. Thanks, Brian Inglis              Calgary, Alberta, Canada

La perfection est atteinte                   Perfection is achieved
non pas lorsqu'il n'y a plus rien à ajouter  not when there is no more to add
mais lorsqu'il n'y a plus rien à retirer     but when there is no more to cut
                                 -- Antoine de Saint-Exupéry

Re: Online documentation revisions

[Sam Edge]

On 26/09/2023 18:00, Brian Inglis wrote:
 > Had a similar issue wanting to see libc docs for Cygwin builds.
 >
 > Check out repo at that rev, configure into out of tree build and 
install dirs, then under e.g. build-3.0.0/newlib run to get into your 
e.g. install-3.0.0/usr/share/{info,man} dirs:
 >
 >     $ make info man && make install info man
 >

Oh well. Guessed as much.

Thanks for the TL;DR instructions. :-)

-- 
Sam Edge

Re: Online documentation revisions

[Sam Edge]

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

On 26/09/2023 18:12, Sam Edge via Newlib wrote:
 > On 26/09/2023 18:00, Brian Inglis wrote:
 > > Had a similar issue wanting to see libc docs for Cygwin builds.
 > >
 > > Check out repo at that rev, configure into out of tree build and
install dirs, then under e.g. build-3.0.0/newlib run to get into your
e.g. install-3.0.0/usr/share/{info,man} dirs:
 > >
 > >     $ make info man && make install info man
 > >
 >
 > Oh well. Guessed as much.
 >
 > Thanks for the TL;DR instructions. :-)
 >

Well, that didn't work - see build.log attached. (Building on a Ubuntu
22.04 LTS based host by the way.)

Oh wait. Those are to build the manual pages. I'm after the one page
HTML document for a non-cygwin bare-metal (e.g. arm-none-eabi-) build,
sorry.

I've cloned from https://sourceware.org/git/newlib-cygwin.git and
checked out newlib-3.0.0 (for example).

I have the GCC cross toolchain available if required but I don't want to
build the binaries, just the all-on-one-page HTML documentation file.

What am I missing?

--
Sam Edge


[-- Attachment #2: build.log --]
[-- Type: text/plain, Size: 4994 bytes --]

samedge@ceres:~/ws/newlib-cygwin
$ git remote -v
origin  https://sourceware.org/git/newlib-cygwin.git (fetch)
origin  https://sourceware.org/git/newlib-cygwin.git (push)
samedge@ceres:~/ws/newlib-cygwin
$ git branch
* (HEAD detached at newlib-3.0.0)
  main
samedge@ceres:~/ws/newlib-cygwin
$ ./configure --prefix=/home/samedge/newlib-3.0.0/
checking build system type... x86_64-pc-linux-gnu
checking host system type... x86_64-pc-linux-gnu
checking target system type... x86_64-pc-linux-gnu
checking for a BSD-compatible install... /usr/bin/install -c
checking whether ln works... yes
checking whether ln -s works... yes
checking for a sed that does not truncate output... /usr/bin/sed
checking for gawk... no
checking for mawk... mawk
checking for gcc... gcc
checking for C compiler default output file name... a.out
checking whether the C compiler works... yes
checking whether we are cross compiling... no
checking for suffix of executables...
checking for suffix of object files... o
checking whether we are using the GNU C compiler... yes
checking whether gcc accepts -g... yes
checking for gcc option to accept ISO C89... none needed
checking for g++... g++
checking whether we are using the GNU C++ compiler... yes
checking whether g++ accepts -g... yes
checking whether g++ accepts -static-libstdc++ -static-libgcc... yes
checking for gnatbind... no
checking for gnatmake... no
checking whether compiler driver understands Ada... no
checking how to compare bootstrapped objects... cmp --ignore-initial=16 $$f1 $$f2
checking for objdir... .libs
checking for isl 0.16, 0.15, or deprecated 0.14... no
recommended isl version is 0.16 or 0.15, the minimum required isl version 0.14 is deprecated
checking for isl 0.16 or 0.15... no
checking for default BUILD_CONFIG...
checking for --enable-vtable-verify... no
*** removing etc/Makefile to force reconfigure
checking for bison... no
checking for byacc... no
checking for yacc... no
checking for bison... no
checking for gm4... no
checking for gnum4... no
checking for m4... no
checking for flex... no
checking for lex... no
checking for flex... no
checking for makeinfo... no
/home/samedge/ws/newlib-cygwin/missing: 81: makeinfo: not found
checking for expect... no
checking for runtest... no
checking for ar... ar
checking for as... as
checking for dlltool... no
checking for ld... ld
checking for lipo... no
checking for nm... nm
checking for ranlib... ranlib
checking for strip... strip
checking for windres... no
checking for windmc... no
checking for objcopy... objcopy
checking for objdump... objdump
checking for readelf... readelf
checking for cc... cc
checking for c++... c++
checking for gcc... gcc
checking for gcj... no
checking for gfortran... no
checking for gccgo... no
checking for ar... ar
checking for as... as
checking for dlltool... no
checking for ld... ld
checking for lipo... no
checking for nm... nm
checking for objcopy... objcopy
checking for objdump... objdump
checking for ranlib... ranlib
checking for readelf... readelf
checking for strip... strip
checking for windres... no
checking for windmc... no
checking where to find the target ar... host tool
checking where to find the target as... host tool
checking where to find the target cc... host tool
checking where to find the target c++... host tool
checking where to find the target c++ for libstdc++... host tool
checking where to find the target dlltool... host tool
checking where to find the target gcc... host tool
checking where to find the target gcj... host tool
checking where to find the target gfortran... host tool
checking where to find the target gccgo... host tool
checking where to find the target ld... host tool
checking where to find the target lipo... host tool
checking where to find the target nm... host tool
checking where to find the target objcopy... host tool
checking where to find the target objdump... host tool
checking where to find the target ranlib... host tool
checking where to find the target readelf... host tool
checking where to find the target strip... host tool
checking where to find the target windres... host tool
checking where to find the target windmc... host tool
checking whether to enable maintainer-specific portions of Makefiles... no
configure: creating ./config.status
config.status: creating Makefile
samedge@ceres:~/ws/newlib-cygwin
$ make info man && make install info man
make[1]: Entering directory '/home/samedge/ws/newlib-cygwin'
Configuring in ./etc
configure: loading cache ./config.cache
checking for a BSD-compatible install... /usr/bin/install -c
configure: creating ./config.status
config.status: creating Makefile
Doing info in etc
make[2]: Entering directory '/home/samedge/ws/newlib-cygwin/etc'
make[2]: Nothing to be done for 'info'.
make[2]: Leaving directory '/home/samedge/ws/newlib-cygwin/etc'
make[1]: Nothing to be done for 'info-target'.
make[1]: Leaving directory '/home/samedge/ws/newlib-cygwin'
make: *** No rule to make target 'man'. Stop.
samedge@ceres:~/ws/newlib-cygwin
$

Re: Online documentation revisions

[Brian Inglis]

On 2023-09-27 02:42, Sam Edge wrote:
> On 26/09/2023 18:12, Sam Edge via Newlib wrote:
>  > On 26/09/2023 18:00, Brian Inglis wrote:
>  > > Had a similar issue wanting to see libc docs for Cygwin builds.
>  > >
>  > > Check out repo at that rev, configure into out of tree build and
> install dirs, then under e.g. build-3.0.0/newlib run to get into your
> e.g. install-3.0.0/usr/share/{info,man} dirs:
>  > >
>  > >     $ make info man && make install info man
>  > >
>  >
>  > Oh well. Guessed as much.
>  >
>  > Thanks for the TL;DR instructions. :-)
>  >
> 
> Well, that didn't work - see build.log attached. (Building on a Ubuntu
> 22.04 LTS based host by the way.)
> 
> Oh wait. Those are to build the manual pages. I'm after the one page
> HTML document for a non-cygwin bare-metal (e.g. arm-none-eabi-) build,
> sorry.
> 
> I've cloned from https://sourceware.org/git/newlib-cygwin.git and
> checked out newlib-3.0.0 (for example).
> 
> I have the GCC cross toolchain available if required but I don't want to
> build the binaries, just the all-on-one-page HTML documentation file.
> 
> What am I missing?

Sorry - doh! - there is a process as part of the build - requires makedoc to be 
built - and install- concatenated try:

	make doc info html && make install-html

We may be treading uncharted waters, and you may need to just pick up the bits 
of html generated, or do a full make to get html generated properly.
See newlib HOWTO!

-- 
Take care. Thanks, Brian Inglis              Calgary, Alberta, Canada

La perfection est atteinte                   Perfection is achieved
non pas lorsqu'il n'y a plus rien à ajouter  not when there is no more to add
mais lorsqu'il n'y a plus rien à retirer     but when there is no more to cut
                                 -- Antoine de Saint-Exupéry

Re: Online documentation revisions

[Sam Edge]

On 27/09/2023 23:19, Brian Inglis wrote:
 > On 2023-09-27 02:42, Sam Edge wrote:
 >> On 26/09/2023 18:12, Sam Edge via Newlib wrote:
 >> [snip]
 >>
 >> I have the GCC cross toolchain available if required but I don't want to
 >> build the binaries, just the all-on-one-page HTML documentation file.
 >>
 >> What am I missing?
 >
 > Sorry - doh! - there is a process as part of the build - requires
makedoc to be built - and install- concatenated try:
 >
 >     make doc info html && make install-html
 >
 > We may be treading uncharted waters, and you may need to just pick up
the bits of html generated, or do a full make to get html generated
properly.
 > See newlib HOWTO!
 >

Thanks Brian.

I was just being lazy asking on here for a shortcut. ;-)

Understanding how to do a full cross-build is probably a good idea anyway.

--
Sam Edge

Re: Online documentation revisions

[Mike Frysinger]

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

On 26 Sep 2023 16:27, Sam Edge via Newlib wrote:
> Is there any way to see the online documentation for Newlib for a given 
> release?
> 
> I often get lumbered with having to use older revisions (3.0.0!) that 
> don't come with source or pre-built HTML or other documentation. (Yes, 
> STM, I'm talking to you!)
> 
> Is there a way to see the state of the online docs at a given revision?

it should be easy to backfill manuals for each release if we wanted.
something like:
https://sourceware.org/newlib/
	# current versions
	libc.html
	libm.html
	libgloss.html
	# old releases
	manual/
		4.3.0/
			libc.html
			libm.html
			libgloss.html
		4.1.0/
			libc.html
			libm.html
			libgloss.html
		...

the html pages are checked into git.  so i could send a patch if someone
would merge it (i don't have push access to the htdocs repo).

there's also pdf and such files, but those are only uploaded to the ftp
server, and i don't have access to that either.

before i write a script to do the backfill, would be nice to hear a signal
from the newlib maintainers that this would be accepted.
-mike

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

Re: Online documentation revisions

[Jeff Johnston]

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

Hi Mike,

Sorry for the late reply.  Yes, this would be accepted and I can merge any
patch you want to make to the htdocs and push any manuals you want to put
on the ftp serer.

-- Jeff J.

On Sun, Oct 15, 2023 at 5:13 AM Mike Frysinger <vapier@gentoo.org> wrote:

> On 26 Sep 2023 16:27, Sam Edge via Newlib wrote:
> > Is there any way to see the online documentation for Newlib for a given
> > release?
> >
> > I often get lumbered with having to use older revisions (3.0.0!) that
> > don't come with source or pre-built HTML or other documentation. (Yes,
> > STM, I'm talking to you!)
> >
> > Is there a way to see the state of the online docs at a given revision?
>
> it should be easy to backfill manuals for each release if we wanted.
> something like:
> https://sourceware.org/newlib/
>         # current versions
>         libc.html
>         libm.html
>         libgloss.html
>         # old releases
>         manual/
>                 4.3.0/
>                         libc.html
>                         libm.html
>                         libgloss.html
>                 4.1.0/
>                         libc.html
>                         libm.html
>                         libgloss.html
>                 ...
>
> the html pages are checked into git.  so i could send a patch if someone
> would merge it (i don't have push access to the htdocs repo).
>
> there's also pdf and such files, but those are only uploaded to the ftp
> server, and i don't have access to that either.
>
> before i write a script to do the backfill, would be nice to hear a signal
> from the newlib maintainers that this would be accepted.
> -mike
>