Documentation patches

[Ralf Hemmecke]

Hi,

I think that I am more or less ready to propose my documentation patch
series:

https://github.com/hemmecke/fricas/commits/formatted

I would like that some persons try out the following.

git clone https://github.com/hemmecke/fricas.git
cd fricas && ./configure && make
cd src/doc
time make -j8 localhtml

That gives the complete website (including the book) locally on your
computer.

In order to produce
https://hemmecke.github.io/fricas/
I used
time make -j8 PACKAGE_SOURCE=https://github.com/hemmecke/fricas
BRANCH=formatted
PACKAGE_VERSION=dc27d6f8d24fbb7a59b9b1c208e5ea960b3943d8
PACKAGE_URL=https://hemmecke.github.io/fricas html

Since I prepared the website for my github account, I had to set some
variables. For the official fricas.github.io "make html" is enough.

The current (non-api) .rst files are just a start. I hope that people
start to contribute. For that I added "edit-on-github" links.

Feedback is acknowledged. I hope I can get this into FriCAS soon.

Ralf

[Grégory Vanuxem]

Le mer. 2 sept. 2020 à 02:58, Ralf Hemmecke <ra...@hemmecke.org> a écrit :
>
> Hi,
>
> I think that I am more or less ready to propose my documentation patch
> series:
>
> https://github.com/hemmecke/fricas/commits/formatted
>
> I would like that some persons try out the following.
>
> git clone https://github.com/hemmecke/fricas.git
> cd fricas && ./configure && make
> cd src/doc
> time make -j8 localhtml

No rules to make target localhtml (or something like that - french message)
even with 'make html'

:-)

(all commands cut and past)

Same things in the fricas directory.
__
Greg


==========================================
PS/

greg@ELLIPSE-LAPTOP:~/fricas$ fricas --version
FriCAS 2020-04-23
based on sbcl 2.0.6.debian
greg@ELLIPSE-LAPTOP:~/fricas$ fricas --help
Usage:
fricas [options]

The following options are recognized.
-clef | -noclef use Clef (default: -clef)
-clefprog fname use named program for Clef
-eval code evaluate specified code at start
-go | -nogo whether to start system
-gr | -nogr use Graphics (default: -gr)
-ht | -noht use HyperDoc (default: -ht)
-ihere| -noihere start an interpreter buffer in the original window
-iw | -noiw start in interpreter window
-list list workspaces only
-nox don't use X Windows
-rl use GNU Readline via rlwrap if available
-ws wsname use named workspace

Some options can only be given in the first position.

Start only a plain commandline interface.
fricas -nosman [-rl] [-eval code]

Print this help screen and exit.
fricas --help

Print version information and exit.
fricas --version

Setup special frontends.
fricas -texmacs
fricas -emacs
greg@ELLIPSE-LAPTOP:~/fricas$


THANKS!

> That gives the complete website (including the book) locally on your
> computer.
>
> In order to produce
> https://hemmecke.github.io/fricas/
> I used
> time make -j8 PACKAGE_SOURCE=https://github.com/hemmecke/fricas
> BRANCH=formatted
> PACKAGE_VERSION=dc27d6f8d24fbb7a59b9b1c208e5ea960b3943d8
> PACKAGE_URL=https://hemmecke.github.io/fricas html
>
> Since I prepared the website for my github account, I had to set some
> variables. For the official fricas.github.io "make html" is enough.
>
> The current (non-api) .rst files are just a start. I hope that people
> start to contribute. For that I added "edit-on-github" links.
>
> Feedback is acknowledged. I hope I can get this into FriCAS soon.
>
> Ralf
>

> --
> You received this message because you are subscribed to the Google Groups "FriCAS - computer algebra system" group.
> To unsubscribe from this group and stop receiving emails from it, send an email to fricas-devel...@googlegroups.com.
> To view this discussion on the web visit https://groups.google.com/d/msgid/fricas-devel/d2689e16-55f0-4d14-e9b0-d544ee91289a%40hemmecke.org.

[Ralf Hemmecke]

>> I would like that some persons try out the following.
>>
>> git clone https://github.com/hemmecke/fricas.git
>> cd fricas && ./configure && make
>> cd src/doc
>> time make -j8 localhtml
>
> No rules to make target localhtml (or something like that - french message)
> even with 'make html'
>
> :-)

Arrrhhhh... ich should have pushed it to the master branch. Try the
following:

git clone https://github.com/hemmecke/fricas.git
cd fricas

git checkout formatted <---- ADDED

./configure && make
cd src/doc
time make -j8 localhtml

Sorry.

Thanks for trying.

Ralf

PS: I can probably decipher french error messages. Fortunately, it is
not as cryptic to me as chinese. ;-)

[Grégory Vanuxem]

Le mer. 2 sept. 2020 à 10:42, Ralf Hemmecke <ra...@hemmecke.org> a écrit :

> Arrrhhhh... ich should have pushed it to the master branch. Try the
> following:
>
> git clone https://github.com/hemmecke/fricas.git
> cd fricas
> git checkout formatted <---- ADDED
> ./configure && make
> cd src/doc
> time make -j8 localhtml

Are you sure? Nothing happens. Only this message:

Branch 'formatted' set up to track remote branch 'formatted' from 'origin'.
Switched to a new branch 'formatted'

Nevertheless I can test a './configure && make'

__
Greg

[Ralf Hemmecke]

Did you also call the last two commands?

cd src/doc
make -j8 localhtml

Since sphinx runs for quite some time on my computer (approx 5 min), it
is not included in the normal build of fricas.

What is probably also still problematic is that changing a .rst file
does not trigger a complete rebuild. For that I would have to register
all the .rst files in the Makefile.in and I didn't think that that would
be a nice idea. Better is to call "make clean-html" if editing a .rst file.

Ralf

[Waldek Hebisch]

On Wed, Sep 02, 2020 at 10:42:46AM +0200, Ralf Hemmecke wrote:
> >> I would like that some persons try out the following.
> >>
> >> git clone https://github.com/hemmecke/fricas.git
> >> cd fricas && ./configure && make
> >> cd src/doc
> >> time make -j8 localhtml
> >
> > No rules to make target localhtml (or something like that - french message)
> > even with 'make html'
> >
> > :-)
>
> Arrrhhhh... ich should have pushed it to the master branch. Try the
> following:
>
> git clone https://github.com/hemmecke/fricas.git
> cd fricas
> git checkout formatted <---- ADDED
> ./configure && make
> cd src/doc
> time make -j8 localhtml

For me build fails:

cd tmp/sphinx && make html
make[2]: Wejscie do katalogu '/mnt/lv0/fricas/axp8/rh3/fricas/src/doc/tmp/sphinx'
/bin/sh: 1: sphinx-build: not found
Makefile:20: polecenia dla obiektu 'html' nie powiodly sie
make[2]: *** [html] Blad 127
make[2]: Opuszczenie katalogu '/mnt/lv0/fricas/axp8/rh3/fricas/src/doc/tmp/sphinx'
Makefile:799: polecenia dla obiektu 'stamp-build-html' nie powiodly sie
make[1]: *** [stamp-build-html] Blad 2
make[1]: *** Oczekiwanie na niezakonczone zadania....

Core thing is clear: I do not have 'sphinx-build' on my machine.
But intead a simply failing, I got a runaway process that used
100% of one core (I gave it 20 minutes and there was no visible
progress, so I do not think it was merely slow).

Clearly one should have requesed tools (which I do not have on
this machine), but failure should be a bit cleaner...

--
Waldek Hebisch

[Ralf Hemmecke]

> cd tmp/sphinx && make html
> make[2]: Wejscie do katalogu '/mnt/lv0/fricas/axp8/rh3/fricas/src/doc/tmp/sphinx'
> /bin/sh: 1: sphinx-build: not found
> Makefile:20: polecenia dla obiektu 'html' nie powiodly sie
> make[2]: *** [html] Blad 127
> make[2]: Opuszczenie katalogu '/mnt/lv0/fricas/axp8/rh3/fricas/src/doc/tmp/sphinx'
> Makefile:799: polecenia dla obiektu 'stamp-build-html' nie powiodly sie
> make[1]: *** [stamp-build-html] Blad 2
> make[1]: *** Oczekiwanie na niezakonczone zadania....

Thank you for testing.

Yes, sphinx should be available. I use Sphinx 3.2.1.
Of course, I could provide some configure options that make the sphinx
build optional if sphinx is not available. However, I somehow think that
putting sphinx (even as a weak) requirement seem to be a bit of an
overkill. And one can easily install sphinx even after running configure
and issue "make html" without affecting the rest of the fricas build.
If I ask for sphinx in configure, I would also have to ask for the
availability of LaTeX (for the book). Could be done, but would you like
it that way or rather just some testing and proper error message in
src/doc/Makefile.in? I would somehow prefer the latter.

> Core thing is clear: I do not have 'sphinx-build' on my machine.

> But intead a simply failing, I got a runaway process that used
> 100% of one core (I gave it 20 minutes and there was no visible
> progress, so I do not think it was merely slow).

OK, I'll try that in a VM. Still I would like to know whether you would
want tests in configure.ac or rather src/doc/Makefile.in.

> Clearly one should have requesed tools (which I do not have on
> this machine), but failure should be a bit cleaner...

Of course.

Ralf

[Grégory Vanuxem]

I follow that. Not as we think.

> --
> You received this message because you are subscribed to the Google Groups "FriCAS - computer algebra system" group.
> To unsubscribe from this group and stop receiving emails from it, send an email to fricas-devel...@googlegroups.com.

> To view this discussion on the web visit https://groups.google.com/d/msgid/fricas-devel/e7843c75-0c40-e30b-2288-66644f683f12%40hemmecke.org.

[Ralf Hemmecke]

BTW, note that for compiling the book you must have the following
packages installed:

epsf
verbatim
hyperref
color
listings
makeidx
xparse
tikz
framed
amsmath
tensor
mleftright

Ralf

[oldk1331]

Hi Ralf,

I compiled the book successfully, it works like a charm!

One comment: to enable pdf hyperlink, you need to use
"latex" to compile the source twice.

Also, can you explain more about your thought behind
commit "compile user guide into book.tex", so that I
can catch up to it and review it more effectively.

Once this is merged, I'd like to improve this documentation
book more.

Best,
Qian

[Ralf Hemmecke]

> I compiled the book successfully, it works like a charm!

Thank you.

> One comment: to enable pdf hyperlink, you need to use
> "latex" to compile the source twice.

book.ps: book.dvi
makeindex book
${MAKE} $<
${MAKE} $<
dvips $<

Oh... OK. Seems like I optimized too much recently, so that latex was
not called as often as I intended. Thanks for the hint. I will look into
this issue.

> Also, can you explain more about your thought behind
> commit "compile user guide into book.tex", so that I
> can catch up to it and review it more effectively.

I don't think it is worth to waste your time with a review, but to
explain the whole process, I need more time. Wait a little. I try to put
the things together. Unfortunatly, although I've put some comments into
src/doc/Makefile.in, it id not soo easy to see what is going on before
latex can be started.

In short.
There are pictures generated (the graphics in the book).
Some .ht pages are created from the .htex files.
The commands in the .htex files are executed and their output is
collected (as tex output) back into the .tex file.

More details later. Maybe I add it to the beginning of the Makefile.in.

> Once this is merged, I'd like to improve this documentation
> book more.

Maybe here our views differ. I somehow tend to keep the book close to
its original form and rather create a new book or other forms of
tutorials, but if more people rather want to see a modernized version of
the content of the book, I am not against such a change. In the end it
is much more important for current users to have helpful documentation.
The historical version of the book can always be retrieved from the time
when my commits are included. That is why we have version control.

Ralf

[Ralf Hemmecke]

Hi Qian,

On 9/9/20 12:19 PM, oldk1331 wrote:
> One comment: to enable pdf hyperlink, you need to use
> "latex" to compile the source twice.

Should be fixed now.

> Also, can you explain more about your thought behind
> commit "compile user guide into book.tex", so that I
> can catch up to it and review it more effectively.

I've now streamlined the variables in src/doc/Makefile.in and rebased
everything on top of the new master branch. Hopefully, I haven't
introduced bugs that weren't there before.

Anyway, at the beginning of the Makefile, you can see a few
explanations. But that is certainly not all that you might want to know.

The changes to the .htex, .spad, .ht files are more or less cosmetics,
since I have tried to reduce the number of different (latex) commands
with the same purpose. Most commands now start with \spad... .

Some additional parts I took from the NAG CDrom that Tim Daly once
provided. The scripts are often a mixture of what was on the CD and my
own adaptations.

Please do not hesitate to ask if you don't understand my mess. It is
always better if more people know how the build system works.

Hopefully it can soon make it into FriCAS.

https://github.com/hemmecke/fricas/commits/formatted

Ralf

[Waldek Hebisch]

On Wed, Sep 09, 2020 at 01:36:19PM +0200, Ralf Hemmecke wrote:
> > I compiled the book successfully, it works like a charm!
>
> Thank you.
>
> > One comment: to enable pdf hyperlink, you need to use
> > "latex" to compile the source twice.
> book.ps: book.dvi
> makeindex book
> ${MAKE} $<
> ${MAKE} $<
> dvips $<
>

Hmm, IIUC running make twice is supposed to produce the same
effect as running it once (on the second run make should note
that book.dvi is up to date and do nothing. In fact, since
book.dvi is a dependency, both make runs above should be
redundant. Correct sulition is to duplicate latex command
or use stamp files if there is need for something more complex.

> > Once this is merged, I'd like to improve this documentation
> > book more.
>
> Maybe here our views differ. I somehow tend to keep the book close to
> its original form and rather create a new book or other forms of
> tutorials, but if more people rather want to see a modernized version of
> the content of the book, I am not against such a change. In the end it
> is much more important for current users to have helpful documentation.
> The historical version of the book can always be retrieved from the time
> when my commits are included. That is why we have version control.

I think that what to do depends on scope of intended work. Clearly
we want small improvement and especially corrections to current
book. OTOH it is better to make larger works separate.

--
Waldek Hebisch

[Ralf Hemmecke]

>>> One comment: to enable pdf hyperlink, you need to use
>>> "latex" to compile the source twice.
>> book.ps: book.dvi
>> makeindex book
>> ${MAKE} $<
>> ${MAKE} $<
>> dvips $<

> Hmm, IIUC running make twice is supposed to produce the same
> effect as running it once (on the second run make should note
> that book.dvi is up to date and do nothing. In fact, since
> book.dvi is a dependency, both make runs above should be
> redundant. Correct sulition is to duplicate latex command
> or use stamp files if there is need for something more complex.

You should look at my updated branch.
As you see here.

https://github.com/hemmecke/fricas/commit/cd75c4a286b99bf41e1b16954711ad3f216ffc76#diff-f1a515130f7da1ea8582b59d082250a2R690

book.dvi: stamp-pics tmp/ug09.tex tmp/info.tex ${HTEX_FILES_TEX}
TEXINPUTS=$$TEXINPUTS:${srcdir}:tmp:. ${LATEX} book.tex \
|| (echo "==> Detected problem while running LaTeX."; \
echo "==> LaTeX must be installed."; \
echo "==> The following LaTeX packages must be available."; \
echo "==> amsmath, breqn, tensor, mleftright, epsf, verbatim,"; \
echo "==> hyperref, color, listings, makeidx, xparse, tikz"; \
exit 1)
if grep 'LaTeX Warning: .*Rerun' book.log; then mv $@ tmp; fi

I now explicitly delete book.dvi if there is this respective LaTeX
Warning in the log file. Then an explicit call to ${MAKE} book.dvi will
try to remake book.dvi and may fail again. However, it might happen that
there is enough information left from a previous ${MAKE} so that a third
"make book.dvi" is not necessary. If running in a clean environment
(with the above removal of book.dvi), latex will be called 3 times.

For development it's nice to have as few latex runs as possible.

Ralf

[Waldek Hebisch]

On Sun, Sep 13, 2020 at 02:30:01AM +0200, Ralf Hemmecke wrote:
>
> Hopefully it can soon make it into FriCAS.
>
> https://github.com/hemmecke/fricas/commits/formatted
>

ATM I can not test documentation build (due to missing dependencies on
my machines). However the code looks OK and since it works for you
and other folks I think it it best to commit it now.

--
Waldek Hebisch

[Ralf Hemmecke]

On 9/23/20 12:36 AM, Waldek Hebisch wrote:
> ATM I can not test documentation build (due to missing dependencies on
> my machines). However the code looks OK and since it works for you
> and other folks I think it it best to commit it now.

I have now merged my patch series and also updated

http://fricas.github.io/

Ralf