Online Emacs Manuals at gnu.org

Online Emacs Manuals at gnu.org

[Yavor Doganov]

We received the first bug report after Chong Yidong (I think)
committed the HTML versions of the manuals at gnu.org.  Karl Berry
asked me to send this message; please keep him in CC.

The exact problem that was reported is:

,----
| in /software/emacs/manual/html_node/Gnus.html#Gnus
| there is a link to the Gnus manual i.e:
| /software/emacs/manual/gnus/index.html#Top (link to gnus)[Gnus].
| ... but the directory "manual/gnus" does not exist :-/
`----

Such things happen because `gendocs.sh' (or `makeinfo' when run
directly) cannot include, for obvious reasons, all the manuals that
are not @include'd from emacs.texi.

Could you upload all of them, please?  (Or alternatively, give green
light for this operation to the GNU Webmasters.)  Either way, we have
to do the .symlinks hack to handle the cross-manual xrefs.

P.S.  The amount of people reading the Emacs manuals online is HUGE.
This is only judging by the bug reports to <webmasters@gnu.org>.  We'd
appreciate if we could reach a general agreement how to handle such
stuff.  Perhaps you could nominate a particular Emacs developer who is
going to deal with these changes (in order not to bother the list) or
grant full vote of confidence to the webmasters' team?  It's entirely
up to you.

Re: Online Emacs Manuals at gnu.org

[Richard Stallman]

    P.S.  The amount of people reading the Emacs manuals online is HUGE.

We need to put in more statements saying "You can buy nice printed
copies from the FSF.  This supports FSF activities."  With a link to
the appropriate page for ordering.  Yavor, can you take care of it?

Re: Online Emacs Manuals at gnu.org

[Richard Stallman]

      We'd
    appreciate if we could reach a general agreement how to handle such
    stuff.  Perhaps you could nominate a particular Emacs developer who is
    going to deal with these changes (in order not to bother the list) or
    grant full vote of confidence to the webmasters' team?

You are welcome to update the Emacs manuals on www.gnu.org, but I
thought the webmasters didn't want to take on such responsibilities.

Re: Online Emacs Manuals at gnu.org

[Chong Yidong]

Yavor Doganov <yavor@gnu.org> writes:

> We received the first bug report after Chong Yidong (I think)
> committed the HTML versions of the manuals at gnu.org.  Karl Berry
> asked me to send this message; please keep him in CC.
>
> The exact problem that was reported is:
>
> ,----
> | in /software/emacs/manual/html_node/Gnus.html#Gnus
> | there is a link to the Gnus manual i.e:
> | /software/emacs/manual/gnus/index.html#Top (link to gnus)[Gnus].
> | ... but the directory "manual/gnus" does not exist :-/
> `----
>
> Such things happen because `gendocs.sh' (or `makeinfo' when run
> directly) cannot include, for obvious reasons, all the manuals that
> are not @include'd from emacs.texi.
>
> Could you upload all of them, please?  (Or alternatively, give green
> light for this operation to the GNU Webmasters.)  Either way, we have
> to do the .symlinks hack to handle the cross-manual xrefs.

Sure.  I've uploaded added the secondary manuals to manual/html_mono
and manual/html_node.

In order to get the links to work properly without lots of symlink
hacking, I had to move the existing manual files around so that they
are where "makeinfo --html" expects.  Thus, the "entirely on one
webpage" version of the emacs manual is now in
manual/html_mono/emacs.html instead of manual/emacs.html, the index
page for the Emacs manual has been moved from manual/index.html to
manual/emacs.html, and the elisp manual has also been merged into the
manual/ tree.

I have tried to update the symlinks by editing the .symlink files, but
this does not seem to have any effect.  Is there anything else I need
to do to make them take effect?  For instance, we need to make the
files in the elisp-manual tree point to the new locations in manual.
Also, we should make a new page in manual/index.html that points to
the separate manuals on the webpage (Emacs manual, elisp manual,
autotype, gnus, etc etc.)

Re: Online Emacs Manuals at gnu.org

[Yavor Doganov]

Richard Stallman wrote:
> 
> We need to put in more statements saying "You can buy nice printed
> copies from the FSF.  This supports FSF activities."  

Sure, but why don't we put it in the gendocs template -- thus every
generated index page will have it.  Of course, not all manuals are
available in printed form, but still it is going to have a positive
effect, I believe.  Karl, what do you think?

> You are welcome to update the Emacs manuals on www.gnu.org, but I
> thought the webmasters didn't want to take on such responsibilities.

Anything under /software is maintainers' territory; some maintainers
do not want random people do edit their pages (and that's
understandable).  We can't manitain every single page because we don't
have the human resources (the www tree is currently ~300 MB, without
/software), but we offer our help in some cases.

For the Emacs manuals particularly, Karl wanted to make some
beautifying of the layout.  We also plan to begin something like a
campaign for the unification of the locations of all GNU manuals, for
better maintainability of gnu.org/manual and the inter-manual links.

Chong Yidong wrote:
> 
> Sure.  I've uploaded added the secondary manuals to manual/html_mono
> and manual/html_node.

Thanks!

> In order to get the links to work properly without lots of symlink
> hacking, I had to move the existing manual files around so that they
> are where "makeinfo --html" expects.  Thus, the "entirely on one
> webpage" version of the emacs manual is now in
> manual/html_mono/emacs.html instead of manual/emacs.html, the index
> page for the Emacs manual has been moved from manual/index.html to
> manual/emacs.html, and the elisp manual has also been merged into the
> manual/ tree.

I think this is what we intended to do, if I'm not wrong.

> I have tried to update the symlinks by editing the .symlink files, but
> this does not seem to have any effect.

It takes 24 hours for the changes to take effect.

> Is there anything else I need to do to make them take effect?  

No, only patience.  If it does not work afterwards, the Savannah
hackers should know the reason and the way to rectify the problem.

Re: Online Emacs Manuals at gnu.org

[Ralf Angeli]

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

* Chong Yidong (2007-06-10) writes:

> In order to get the links to work properly without lots of symlink
> hacking, I had to move the existing manual files around so that they
> are where "makeinfo --html" expects.  Thus, the "entirely on one
> webpage" version of the emacs manual is now in
> manual/html_mono/emacs.html instead of manual/emacs.html, the index
> page for the Emacs manual has been moved from manual/index.html to
> manual/emacs.html, and the elisp manual has also been merged into the
> manual/ tree.

We have a similar setup with AUCTeX, preview-latex, and RefTeX.  You can
see that in action at <URL:http://www.gnu.org/software/auctex/manual/>.

I set this up by patching gendocs.sh (see attachment; not sure if this
will apply cleanly) and using a htmlxref.cnf file for managing the cross
references.

It would be nice if gendocs.sh would support a setup with multiple
manuals in one `manual' directory by default.

-- 
Ralf

[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: gendocs.sh.patch --]
[-- Type: text/x-diff, Size: 1887 bytes --]

--- /usr/src/reftex/prog/reftex/gendocs.sh~	2007-04-11 19:35:34 +0200
+++ /usr/src/reftex/prog/reftex/gendocs.sh	2007-04-11 19:28:59 +0200
@@ -32,6 +32,7 @@
 
 : ${SETLANG="env LANG= LC_MESSAGES= LC_ALL= LANGUAGE="}
 : ${MAKEINFO="makeinfo"}
+: ${TEXI2HTML="texi2html"}
 : ${TEXI2DVI="texi2dvi -t @finalout"}
 : ${DVIPS="dvips"}
 : ${DOCBOOK2HTML="docbook2html"}
@@ -195,7 +196,7 @@
 ascii_gz_size=`calcsize $outdir/$PACKAGE.txt.gz`
 mv $PACKAGE.txt $outdir/
 
-cmd="$SETLANG $MAKEINFO --no-split --html -o $PACKAGE.html $html \"$srcfile\""
+cmd="$SETLANG $TEXI2HTML -o $PACKAGE.html $html \"$srcfile\""
 echo "Generating monolithic html... ($cmd)"
 rm -rf $PACKAGE.html  # in case a directory is left over
 eval "$cmd"
@@ -204,7 +205,7 @@
 html_mono_gz_size=`calcsize $outdir/$PACKAGE.html.gz`
 mv $PACKAGE.html $outdir/
 
-cmd="$SETLANG $MAKEINFO --html -o $PACKAGE.html $html \"$srcfile\""
+cmd="$SETLANG $TEXI2HTML --split=node --use-nodes --node-files --top-file=\"index.html\" -o $PACKAGE.html $html \"$srcfile\""
 echo "Generating html by node... ($cmd)"
 eval "$cmd"
 split_html_dir=$PACKAGE.html
@@ -213,9 +214,9 @@
   tar -czf ../$outdir/${PACKAGE}.html_node.tar.gz -- *.html
 )
 html_node_tgz_size=`calcsize $outdir/${PACKAGE}.html_node.tar.gz`
-rm -f $outdir/html_node/*.html
-mkdir -p $outdir/html_node/
-mv ${split_html_dir}/*.html $outdir/html_node/
+rm -f $outdir/${PACKAGE}/*.html
+mkdir -p $outdir/${PACKAGE}/
+mv ${split_html_dir}/*.html $outdir/${PACKAGE}/
 rmdir ${split_html_dir}
 
 echo Making .tar.gz for sources...
@@ -290,7 +291,7 @@
    -e "s!%%DOCBOOK_XML_GZ_SIZE%%!$docbook_xml_gz_size!g" \
    -e "s,%%SCRIPTURL%%,$scripturl,g" \
    -e "s!%%SCRIPTNAME%%!$prog!g" \
-$GENDOCS_TEMPLATE_DIR/gendocs_template >$outdir/index.html
+$GENDOCS_TEMPLATE_DIR/gendocs_template >$outdir/${PACKAGE}.index.html
 
 echo "Done!  See $outdir/ subdirectory for new files."
 

[-- Attachment #3: Type: text/plain, Size: 142 bytes --]

_______________________________________________
Emacs-devel mailing list
Emacs-devel@gnu.org
http://lists.gnu.org/mailman/listinfo/emacs-devel

Re: Online Emacs Manuals at gnu.org

[Richard Stallman]

      We can't manitain every single page because we don't
    have the human resources (the www tree is currently ~300 MB, without
    /software), but we offer our help in some cases.

If you want to help, and have time, please help.

Re: Online Emacs Manuals at gnu.org

[Chong Yidong]

Yavor Doganov <yavor@gnu.org> writes:

>> I have tried to update the symlinks by editing the .symlink files, but
>> this does not seem to have any effect.
>
> It takes 24 hours for the changes to take effect.

I am not sure the .symlinks file is working correctly -- could you
help me check?

The original location for the elisp manual was
software/gnu/emacs/elisp-manual/index.html, and this has been moved to
software/gnu/emacs/manual/elisp.html.  So, in
software/gnu/emacs/elisp-manual/.symlinks, I put

../manual/elisp.html index.html
../manual/elisp.html elisp.html

Is this correct?  Or should this instead be

software/gnu/emacs/manual/elisp.html

or 

/software/gnu/emacs/manual/elisp.html?

Re: Online Emacs Manuals at gnu.org

[Miles Bader]

Yavor Doganov <yavor@gnu.org> writes:
> We also plan to begin something like a campaign for the unification of
> the locations of all GNU manuals, for better maintainability of
> gnu.org/manual and the inter-manual links.

That sounds really nice!

In fact, I never even knew about gnu.org/manual (hmmm I dunno am I just
blind?); even in it's current form it looks very useful.

BTW, a lot of the pages still say "no GIFs due to patent problems".
[Actually, even though patent is expired, is there really any reason to
distribute images in the GIF format any more (outside special cases like
animations)?  My impression is that pretty much everything can handle
PNG files these days...]

-miles
...who doesn't have enough disk space on his home machine for
documentation... :-}

-- 
=====
(^o^;
(()))
*This is the cute octopus virus, please copy it into your sig so it can spread.

Re: Online Emacs Manuals at gnu.org

[Yavor Doganov]

Chong Yidong wrote:
> 
> So, in
> software/gnu/emacs/elisp-manual/.symlinks, I put

Without "gnu", I think.

> ../manual/elisp.html index.html
> ../manual/elisp.html elisp.html
> 
> Is this correct?  

Yes, that's correct.

Richard Stallman wrote:
> 
> What is the gendocs template, and what is generated with it?

This is the HTML template used in conjunction with the gendocs.sh
script (it is mentioned in maintain.texi).  The script transforms the
Texinfo source in various formats and creates an index.html page with
hyperlinks to them.  Most of the GNU maintainers are using it.

Re: Online Emacs Manuals at gnu.org

[Chong Yidong]

Yavor Doganov <yavor@gnu.org> writes:

> Chong Yidong wrote:
>> 
>> So, in
>> software/gnu/emacs/elisp-manual/.symlinks, I put
>
> Without "gnu", I think.
>
>> ../manual/elisp.html index.html
>> ../manual/elisp.html elisp.html
>> 
>> Is this correct?  
>
> Yes, that's correct.

It doesn't seem to be working.  Could you take a look?

Ideally, we should also have symlinks from elisp-manual/html_mono to
manual/html_mono, and from elisp-manual/html_node to
elisp-manual/html_node/elisp, so that old links to the elisp manual
will still work.  Can the symlinks system handle directories?

Re: Online Emacs Manuals at gnu.org

[Yavor Doganov]

Chong Yidong wrote:
> 
> >> ../manual/elisp.html index.html
> >> ../manual/elisp.html elisp.html
> 
> It doesn't seem to be working.

It works only for the index page, that's expected.  Now
http://www.gnu.org/software/emacs/elisp-manual/ displays the
gendocs-generated index of the Emacs Lisp Reference Manual.

In order the links to the various formats to work, we either have to
regenerate the page when Karl changes the script to handle the new
locations (if he doesn't see a problem with the new layout), or
install symlinks in each subdirectory.  And certainly I can do that
manually, no big deal.

> Ideally, we should also have symlinks [...] so that old links to the
> elisp manual will still work.

I just did that, let's wait and see if it works.

> Can the symlinks system handle directories?

Several people have reported that they don't work, but we already have
working symlinks like "foo bar".  I don't see a particular reason why
"foo/baz bar" won't work.

What's certain is that the second filename cannot contain slashes;
wildcards are also out of question.

Re: Online Emacs Manuals at gnu.org

[Richard Stallman]

    This is the HTML template used in conjunction with the gendocs.sh
    script (it is mentioned in maintain.texi).  The script transforms the
    Texinfo source in various formats and creates an index.html page with
    hyperlinks to them.  Most of the GNU maintainers are using it.

Then I think it was a good suggestion to make it generate something
about buying GNU manuals.

Re: Online Emacs Manuals at gnu.org

[Yavor Doganov]

В Tue, 12 Jun 2007 13:02:59 +0900, Miles Bader написа:

> BTW, a lot of the pages still say "no GIFs due to patent problems".

These are probably old pages under /software/<package>.  We have amended 
http://gnu.org/philosophy/gif.html to reflect the current situation, but 
we still discourage GIF images.  The fact that the patent expired is not 
a reason to promote this format.