Guile web page docs

[Neil Jerram]

I noticed that the docs on the Guile web pages are a bit out of date.
The 1.8 ones are behind those in 1.8.7 (the latest release).  I'm not
sure about the 1.6 ones, but will check.  And there aren't any docs for
1.9/2.0 at all - which I think would be useful.

Would anyone object if we added a 1.9/2.0 set, and updated all these to
correspond to the latest available (i.e. from CVS/Git) in each release
series?

Thanks,
        Neil

[Ludovic Courtès-3]

Neil Jerram <neil@...> writes:

> I noticed that the docs on the Guile web pages are a bit out of date.
> The 1.8 ones are behind those in 1.8.7 (the latest release).

http://www.gnu.org/software/guile/manual/html_node/index.html appears to
correspond to 1.8.7.

(BTW, Gnulib has a new script to automate updates to
www.gnu.org/software/PROJECT/manual.)

> Would anyone object if we added a 1.9/2.0 set, and updated all these to
> correspond to the latest available (i.e. from CVS/Git) in each release
> series?

I hadn't done it so far, mostly because 1.9 is alpha, and I think
gnu.org/software/guile/manual should point to the current stable series.
That said, perhaps we could put them in a sub-directory.

What do you think?

Thanks,
Ludo'.

[Neil Jerram]

ludo@... (Ludovic Courtès) writes:

> Neil Jerram <neil@...> writes:
>
>> I noticed that the docs on the Guile web pages are a bit out of date.
>> The 1.8 ones are behind those in 1.8.7 (the latest release).
>
> http://www.gnu.org/software/guile/manual/html_node/index.html appears to
> correspond to 1.8.7.

Yes, but amusingly this copy of the manual is only linked from the
"support for many SRFIs" link on
http://www.gnu.org/software/guile/guile.html, and from inside Daniel's
tutorial.

If you follow the more prominent links from
http://www.gnu.org/software/guile/, you get to
http://www.gnu.org/software/guile/docs/docs-1.8/guile-ref/index.html,
which is still at version 1.8.1.

So, anyway, I think we agree that this needs sorting out!

> (BTW, Gnulib has a new script to automate updates to
> www.gnu.org/software/PROJECT/manual.)

Right; I assume you mean gendocs.sh.

>> Would anyone object if we added a 1.9/2.0 set, and updated all these to
>> correspond to the latest available (i.e. from CVS/Git) in each release
>> series?
>
> I hadn't done it so far, mostly because 1.9 is alpha, and I think
> gnu.org/software/guile/manual should point to the current stable series.
> That said, perhaps we could put them in a sub-directory.

Yes, that's what I had in mind, linked from
http://www.gnu.org/software/guile/docs/docs.html.

Do you have strong views on whether we should use current Git or the
latest pre-release?  I don't think it matters much, and current Git is
marginally easier.

Regards,
        Neil

[Ludovic Courtès-3]

Hi,

Neil Jerram <neil@...> writes:

> ludo@... (Ludovic Courtès) writes:
>
>> Neil Jerram <neil@...> writes:
>>
>>> I noticed that the docs on the Guile web pages are a bit out of date.
>>> The 1.8 ones are behind those in 1.8.7 (the latest release).
>>
>> http://www.gnu.org/software/guile/manual/html_node/index.html appears to
>> correspond to 1.8.7.
>
> Yes, but amusingly this copy of the manual is only linked from the
> "support for many SRFIs" link on
> http://www.gnu.org/software/guile/guile.html, and from inside Daniel's
> tutorial.

And from http://gnu.org/manual/ .

> If you follow the more prominent links from
> http://www.gnu.org/software/guile/, you get to
> http://www.gnu.org/software/guile/docs/docs-1.8/guile-ref/index.html,
> which is still at version 1.8.1.
>
> So, anyway, I think we agree that this needs sorting out!

Indeed.  I think I’ve always been updating the one at guile/manual,
since it’s the usual way to place GNU manuals, but I must have forgotten
to check the links under guile/.  I’d be in favor or removing ‘docs-1.8’
and keeping just ‘manual’.  What do you think?

>> (BTW, Gnulib has a new script to automate updates to
>> www.gnu.org/software/PROJECT/manual.)
>
> Right; I assume you mean gendocs.sh.

I was thinking about the ‘gnu-web-doc-update’ module.

>> I hadn't done it so far, mostly because 1.9 is alpha, and I think
>> gnu.org/software/guile/manual should point to the current stable series.
>> That said, perhaps we could put them in a sub-directory.
>
> Yes, that's what I had in mind, linked from
> http://www.gnu.org/software/guile/docs/docs.html.

OK.

> Do you have strong views on whether we should use current Git or the
> latest pre-release?  I don't think it matters much, and current Git is
> marginally easier.

Either way is fine with me.

Thank you!

Ludo’.

[Neil Jerram]

ludo@... (Ludovic Courtès) writes:

> Hi,
>
> Neil Jerram <neil@...> writes:
>
>> Yes, but amusingly this copy of the manual is only linked from the
>> "support for many SRFIs" link on
>> http://www.gnu.org/software/guile/guile.html, and from inside Daniel's
>> tutorial.
>
> And from http://gnu.org/manual/ .

Ah, thanks.

> Indeed.  I think I’ve always been updating the one at guile/manual,
> since it’s the usual way to place GNU manuals, but I must have forgotten
> to check the links under guile/.  I’d be in favor or removing ‘docs-1.8’
> and keeping just ‘manual’.  What do you think?

Agreed, and I've done that now.

>>> (BTW, Gnulib has a new script to automate updates to
>>> www.gnu.org/software/PROJECT/manual.)
>>
>> Right; I assume you mean gendocs.sh.
>
> I was thinking about the ‘gnu-web-doc-update’ module.

I'll take a look, thanks.

>> Do you have strong views on whether we should use current Git or the
>> latest pre-release?  I don't think it matters much, and current Git is
>> marginally easier.
>
> Either way is fine with me.

Cool, I'll sort out a 1.9/2.0 set of docs later.

      Neil

[Neil Jerram]

Neil Jerram <neil@...> writes:

> Cool, I'll sort out a 1.9/2.0 set of docs later.

This is up now.

     Neil

[Neil Jerram]

>>>> (BTW, Gnulib has a new script to automate updates to
>>>> www.gnu.org/software/PROJECT/manual.)
>>>
>>> Right; I assume you mean gendocs.sh.
>>
>> I was thinking about the ‘gnu-web-doc-update’ module.
>
> I'll take a look, thanks.

[guile-user trimmed]

This doesn't look so useful to me.  It makes assumptions about the
package that don't hold for Guile: a bootstrap script (our autogen.sh);
manual in doc/manual; and a `make web-manual' Makefile target.

We could make Guile conform to those assumptions, but I'm not sure it's
worth it.  Isn't it already pretty easy to use gendocs.sh, copy the
generated files into the web-pages tree, and commit?  (I've actually
never used gendocs.sh.)

Certainly for the 1.9/2.0 docs, it's trivial to just do `make html'
followed by `cp -a doc/ref/guile.html ../web-pages/docs/master/'.

     Neil

[Ludovic Courtès-3]

Hi,

Neil Jerram <neil@...> writes:

>>>>> (BTW, Gnulib has a new script to automate updates to
>>>>> www.gnu.org/software/PROJECT/manual.)
>>>>
>>>> Right; I assume you mean gendocs.sh.
>>>
>>> I was thinking about the ‘gnu-web-doc-update’ module.
>>
>> I'll take a look, thanks.
>
> [guile-user trimmed]
>
> This doesn't look so useful to me.  It makes assumptions about the
> package that don't hold for Guile: a bootstrap script (our autogen.sh);
> manual in doc/manual; and a `make web-manual' Makefile target.

Hmm, OK.  I’ve never actually used it and I didn’t know that.

> We could make Guile conform to those assumptions, but I'm not sure it's
> worth it.

Agreed.

> Isn't it already pretty easy to use gendocs.sh, copy the generated
> files into the web-pages tree, and commit?  (I've actually never used
> gendocs.sh.)

That’s what I’ve been doing so far.  It’s slightly tedious because run
gendocs.sh with the right parameters, have a cvs checkout, copy files
there, add the new ones (and ideally remove the obsolete ones), then
check-in and wait for ages.

Maybe that actually calls for a ‘web-manual’ makefile target?  :-)

Thanks,
Ludo’.

[Andy Wingo]

On Thu 29 Oct 2009 00:20, ludo@... (Ludovic Courtès) writes:

> Neil Jerram <neil@...> writes:
>
>>>>>> (BTW, Gnulib has a new script to automate updates to
>>>>>> www.gnu.org/software/PROJECT/manual.)
>>>>>
>>>>> Right; I assume you mean gendocs.sh.
>>>>
>>>> I was thinking about the ‘gnu-web-doc-update’ module.
>>>
>>> I'll take a look, thanks.
>>
>> [guile-user trimmed]
>>
>> This doesn't look so useful to me.  It makes assumptions about the
>> package that don't hold for Guile: a bootstrap script (our autogen.sh);
>> manual in doc/manual; and a `make web-manual' Makefile target.
>
> Hmm, OK.  I’ve never actually used it and I didn’t know that.
>
>> We could make Guile conform to those assumptions, but I'm not sure it's
>> worth it.
>
> Agreed.
>
>> Isn't it already pretty easy to use gendocs.sh, copy the generated
>> files into the web-pages tree, and commit?  (I've actually never used
>> gendocs.sh.)
>
> That’s what I’ve been doing so far.  It’s slightly tedious because run
> gendocs.sh with the right parameters, have a cvs checkout, copy files
> there, add the new ones (and ideally remove the obsolete ones), then
> check-in and wait for ages.

It's possible to automate this. The crux of it is "cvs import" :)

dir=~/src/guile-gnome/platform/gtk/doc/gtk
file=guile-gnome-gtk

all:
        @echo "try make update"

index.html: %.html: %.scm
        ( guile --debug -l $< -c '(make-index)' > $@ || { rm $@; false; } )

update: index.html
        rm -rf html
        ( export tmp=`mktemp -d`; \
          export cur=`pwd`; \
          cd $$tmp; \
          mkdir $(file); \
          cp -a $(dir)/*.texi $(file)/; \
          tar czvf $(file).texi.tar.gz $(file); \
          cp $(file).texi.tar.gz $$cur/; \
          cd $(file); \
          makeinfo $(file).texi; \
          tar czvf $(file).info.tar.gz $(file).info*; \
          cp $(file).info.tar.gz $$cur/; \
          makeinfo -o $$cur/html --html $(file).texi; \
          texi2dvi -o $(file).dvi -q $(file).texi; \
          dvips $(file) -o; \
          gzip -9 $(file).ps; \
          cp $(file).ps.gz $$cur/; \
          gzip -9 $(file).dvi; \
          cp $(file).dvi.gz $$cur/; \
          texi2pdf --pdf -o $$cur/$(file).pdf -q $(file).texi; \
          cd $$cur; \
          rm -rf $$tmp; \
        )
        ( export CVSDIR=$(shell cat ../CVS/Root); cvs -d $$CVSDIR import -m 'update manual' guile-gnome/docs/$(shell basename `pwd`) gnu $(shell date "+D%Y%m%d%H%M%S"))

--
http://wingolog.org/