search

rtoy / maxima

A Clone of Maxima's repo
Other
0 stars 0 forks source link

Broken HTML documentation (5.43.0) #3343

Closed rtoy closed 3 months ago

rtoy commented 3 months ago

Imported from SourceForge on 2024-07-07 20:57:12 Created by villate on 2019-06-09 12:01:37 Original: https://sourceforge.net/p/maxima/bugs/3560

The HTML manual in version 5.43.0, has some serious problems:

  1. The table of contents, whcih used to be created in a file maxima_toc.html, is now appended to the function and variables index, which will be in a file with different names every time the manual is modified (it ccurrently has the name maxima_92.html). That breaks the links to browse the manual in the "Help" menu of Xmaxima, which points to the non-existent maxima_toc.html.
  2. The main HTML page, which used to be named maxima.html, is now named maxima_0.html. The website pages could be modified to point to maxima_0.html instead of maxima.html, but the search engines already have links to maxima.html in the Maxima website. Perhaps a link from maxima.html to maxima_0.html could be generated automatically when the documentation is created?
  3. The main page (maxima_0.html) has links to non-existent HTML pages.
rtoy commented 3 months ago

Imported from SourceForge on 2024-07-07 20:57:13 Created by tomio-arisaka on 2019-06-18 17:35:31 Original: https://sourceforge.net/p/maxima/bugs/3560/#93c8

This is my temporary solution:

$ git clone https://git.code.sf.net/p/maxima/code maxima-code
$ cp -iRp ./maxima-code ./maxima-542
$ cd ./maxima-542/
$ git checkout d87828d4ef61b8062b26999faa8e24cdb175d815
$ cp -fp ../maxima-code/doc/info/*.texi ./doc/info/
$ cp -ip ./doc/info/Makefile.am ./doc/info/Makefile.am.orig
$ nano ./doc/info/Makefile.am
$ diff -u doc/info/Makefile.am.orig doc/info/Makefile.am
--- doc/info/Makefile.am.orig   2019-06-18 21:20:11.000000000 +0900
+++ doc/info/Makefile.am    2019-06-18 21:36:13.000000000 +0900
@@ -44,7 +44,7 @@
  Runtime.texi Miscellaneous.texi Rules.texi nset.texi Function.texi \
  Program.texi Debugging.texi alt-display.texi asympa.texi \
  augmented_lagrangian.texi bitwise.texi bernstein.texi bode.texi celine.texi \
- clebsch_gordan.texi combinatorics.texi \
+ clebsch_gordan.texi combinatorics.texi odepack.texi \
  cobyla.texi contrib_ode.texi descriptive.texi diag.texi distrib.texi \
  draw.texi drawdf.texi dynamics.texi engineering-format.texi \
  wrstcse.texi ezunits.texi f90.texi finance.texi \
@@ -150,6 +150,7 @@
 figures/draw_color.gif\
 figures/draw_color2.gif\
 figures/draw_color3.gif\
+figures/draw_color4.gif\
 figures/draw_columns.gif\
 figures/draw_contour2.gif\
 figures/draw_contour.gif\
@@ -370,6 +371,7 @@
 figures/draw_color.pdf\
 figures/draw_color2.pdf\
 figures/draw_color3.pdf\
+figures/draw_color4.pdf\
 figures/draw_columns.pdf\
 figures/draw_contour2.pdf\
 figures/draw_contour.pdf\
$ 
$ cp -ip ./doc/info/include-maxima.texi.in ./doc/info/include-maxima.texi.in.orig
$ cp -fp ../maxima-code/doc/info/include-maxima.texi.in ./doc/info/
$ cp -fp ../maxima-code/doc/info/figures/draw_color4.* ./doc/info/figures/
$ cp -fp ../maxima-code/doc/info/figures/Makefile.am ./doc/info/figures/
$ cd ..
$ 
$ cd ./maxima-code/
$ cp -ip ./configure.ac ./configure.ac.orig
$ nano ./configure.ac
$ diff -u configure.ac.orig configure.ac
--- configure.ac.orig   2019-06-18 21:13:36.000000000 +0900
+++ configure.ac    2019-06-18 23:09:35.000000000 +0900
@@ -1254,8 +1254,8 @@
 AC_CONFIG_FILES([src/startmaxima_abcl.sh], chmod +x src/startmaxima_abcl.sh)
 AC_CONFIG_FILES([xmaxima-local], chmod +x xmaxima-local)
 AC_CONFIG_FILES([tests/test.sh], chmod +x tests/test.sh)
-AC_CONFIG_FILES([doc/info/build_html.sh], chmod +x doc/info/build_html.sh)
-AC_CONFIG_FILES([doc/info/extract_categories.sh], chmod +x doc/info/extract_categories.sh)
+# AC_CONFIG_FILES([doc/info/build_html.sh], chmod +x doc/info/build_html.sh)
+# AC_CONFIG_FILES([doc/info/extract_categories.sh], chmod +x doc/info/extract_categories.sh)

 # Convert maxima.bat to DOS line ending
 # sed-3.02 in old mingw distribution doesn't support -i or \r
$ 
$ mv -i ./doc/info ./doc/info.orig
$ cp -iRp ../maxima-542/doc/info ./doc/
$ 
$ ./bootstrap 
$ 
$ M_PREFIX=${HOME}/sw
$ ./configure --prefix=${M_PREFIX} --enable-gettext --enable-recode --enable-sbcl-exec
$ make
$ make install
rtoy commented 3 months ago

Imported from SourceForge on 2024-07-07 20:57:17 Created by villate on 2019-06-19 06:56:43 Original: https://sourceforge.net/p/maxima/bugs/3560/#ca59

Thanks Tomio, I will try out your patch.

rtoy commented 3 months ago

Imported from SourceForge on 2024-07-07 20:57:20 Created by villate on 2019-06-19 11:29:36 Original: https://sourceforge.net/p/maxima/bugs/3560/#dffc

If I understand Tomio's patch correctly, it just uses the old documentation in version 5.42, doing some updates. That's in fact a very temporary solution. The problem remains: how to make the new version of texinfo build a table of contents, and only URLs that do exist.

rtoy commented 3 months ago

Imported from SourceForge on 2024-07-07 20:57:24 Created by tomio-arisaka on 2019-06-20 11:12:34 Original: https://sourceforge.net/p/maxima/bugs/3560/#707a

Your understanding of my shell-script is right.

I think that both Xmaxima and wxMaxima depend on an output of texi2html. The texi2html is included in Maxima. It seems that the HTML output is controlled. When changing texi2html to texi2any, HTML output is changed. So It's no wonder that the help system of Xmaxima and wxMaxima does not work.

I'm not interested in how to create HTML files. But I want to get HTML files which are compatible with both Xmaxima and wxMaxima. I hope that my solution will be very temporary.

By the way, if texi2any cannot create Xmaxima compatible HTML files, I think both Xmaxima and wxMaxima must be modified.

rtoy commented 3 months ago

Imported from SourceForge on 2024-07-07 20:57:27 Created by tomio-arisaka on 2019-07-03 14:28:43 Original: https://sourceforge.net/p/maxima/bugs/3560/#0208

I tried to modify the HTML files created by texi2any in order to make Xmaxima parse them. See https://sourceforge.net/p/maxima/mailman/message/36706902/

This is my example:

# fetch the branch rtoy-fixup-html-docs from git server and compile it
#
# M_PREFIX is the path in which Maxima is installed
M_PREFIX=${HOME}/sw2
export PATH=${M_PREFIX}/bin:$PATH
GITDIR=maxima-rtoy2
git clone https://git.code.sf.net/p/maxima/code ${GITDIR}
cd ${GITDIR}
git checkout remotes/origin/rtoy-fixup-html-docs
./bootstrap
./configure --prefix=${M_PREFIX} --enable-gettext --enable-recode --enable-sbcl-exec
make
make install
cd ..

# modify the HTML files created by texi2any in order to make Xmaxima parse them
#
# replace "•" with "*"
find ${M_PREFIX} -iname '*maxima_*.html' -exec perl -pi -e 's|•|*|g' {} +
#
# replace "<span id></span>" with "<a name></a>"
find ${M_PREFIX} -iname '*maxima_*.html' -exec perl -pi -e 's|<span\s+id="(.+?)"></span>|<a name="\1"></a>|g' {} +
#
# replace "<th id></th>" with "<th><a name></a></th>"
find ${M_PREFIX} -iname '*maxima_*.html' -exec perl -pi -e 's|<th\s+id="(.+?)">(.+?)</th>|<th><a name="\1">\2</a></th>|g' {} +
rtoy commented 3 months ago

Imported from SourceForge on 2024-07-07 20:57:31 Created by tomio-arisaka on 2019-07-08 18:40:08 Original: https://sourceforge.net/p/maxima/bugs/3560/#733a

Additional patch for Xmaxima:

#
# replace "<dt id>" with "<dt><a name></a>"
find ${M_PREFIX} -iname '*maxima_*.html' -exec perl -pi -e 's|<dt\s+id="(.+?)">|<dt><a name="\1"></a>|g' {} +
#
# replace "<a id>" with "<a name>"
find ${M_PREFIX} -iname '*maxima_*.html' -exec perl -pi -e 's|<a\s+id="(.+?)"|<a name="\1"|g' {} +

So I think the HTML anchor issue was solved.

I'm using the version 6.6 of texi2any. So my patch should be applied to the HTML files created by texi2any-6.6. I don't know the other versions of texi2any.

rtoy commented 3 months ago

Imported from SourceForge on 2024-07-07 20:57:34 Created by robert_dodier on 2020-01-30 23:49:12 Original: https://sourceforge.net/p/maxima/bugs/3560/#9e74

Jaime, I think that items 1 and 2 have been fixed recently in Git. Can you see if the current version works for you?

About 3, I tried some links on the main page and they seem to work OK. If there are still some broken links, can you say what they are?

rtoy commented 3 months ago

Imported from SourceForge on 2024-07-07 20:57:38 Created by robert_dodier on 2022-09-23 02:26:16 Original: https://sourceforge.net/p/maxima/bugs/3560/#9107

rtoy commented 3 months ago

Imported from SourceForge on 2024-07-07 20:57:41 Created by robert_dodier on 2023-02-26 06:25:15 Original: https://sourceforge.net/p/maxima/bugs/3560/#4a52

rtoy commented 3 months ago

Imported from SourceForge on 2024-07-07 20:57:45 Created by robert_dodier on 2023-02-26 06:25:15 Original: https://sourceforge.net/p/maxima/bugs/3560/#71a5

Pretty sure problems (1) and (2) have been fixed in recent versions.

About problem (3), when there is some specific broken link identified, we can open a new bug report specifically for that.

Closing this item as fixed.