help files in src/doc (issue : #112)

[Grégory Vanuxem]

Hello,

Following issue #112 where I reported that the .help files for the
interpreter are not installed with configure option '--with-x=no'. I
recently reported that they are not uninstalled too. In fact when I
told to Ralf that he's the author of the build machinery (Makefile)
for src/doc/ I asked him if he can fix the issue related to not be
able to use the ')help' system command, I may have made a mistake. It
seems also related to the ./configure step. I looked at configure.ac
and near line 755 we can read:

===================================================
if test x"$fricas_has_xpm" = xyes; then
AC_CHECK_HEADER([regex.h],
[fricas_src_all="$fricas_src_all all-hyper all-doc"
fricas_src_subdirs="$fricas_src_subdirs hyper doc"
AC_CHECK_PROGS([XVFB_RUN], [xvfb-run])
if test -n "$XVFB_RUN"; then
MAYBE_VIEWPORTS=viewports
XVFB="xvfb-run -a -s '-screen 0 1024x768x24'"
else
AC_MSG_NOTICE([HyperDoc graphics must be built
separately.])
fi
],
[AC_MSG_NOTICE([HyperDoc is disabled.])])
fi
# We need the Makefile (for util.ht) even if we do not build HyperDoc.
FRICAS_MAKEFILE([src/hyper/Makefile])
FRICAS_MAKEFILE([src/doc/Makefile])
=============================================

Apparently $fricas_src_subdirs 'doc' need libxpm and even regex.h.
So as _a proof of concept_ I moved this just after:

==============================================
if test x"$fricas_has_xpm" = xyes; then
AC_CHECK_HEADER([regex.h],
[fricas_src_all="$fricas_src_all all-hyper all-doc"
fricas_src_subdirs="$fricas_src_subdirs hyper"
AC_CHECK_PROGS([XVFB_RUN], [xvfb-run])
if test -n "$XVFB_RUN"; then
MAYBE_VIEWPORTS=viewports
XVFB="xvfb-run -a -s '-screen 0 1024x768x24'"
else
AC_MSG_NOTICE([HyperDoc graphics must be built
separately.])
fi
],
[AC_MSG_NOTICE([HyperDoc is disabled.])])
fi
# We need the Makefile (for util.ht) even if we do not build HyperDoc.
FRICAS_MAKEFILE([src/hyper/Makefile])
fricas_src_subdirs="$fricas_src_subdirs doc"
FRICAS_MAKEFILE([src/doc/Makefile])
==============================================

After a 'autoconf2.69' [1], with this modification, help files are
correctly deleted with a 'make clean' or 'make distclean'.
(-with-x=no or yes).

Regards,
__
Greg


[1] BTW, I wonder why you are still using the 2.69 version of autoconf.

[Ralf Hemmecke]

Hi Greg,

your idea looks OK. However, als I have already told you in a private
Mail, since no graphics is working (because of --with-x=no),
"cd src/doc; make book.pdf".

Well, now one can take the position that this is clear that it will not
work, since "--with-x=no" was given, but in some sense I'd prefer that
'make book.pdf" in this case rather stops immediately instead of
starting to run fricas only to hang while being ask to produce the
moebius graphic.

In other words, I would like to change the Makefile in such a way that
"make book.pdf" is not available or gives an error immediately.

Other opiniouns?

Ralf

[Ralf Hemmecke]

Hi Waldek,

I looked a bit deeper into this issue of compilation with --with-x=no.

The problem seems to be that I did not consider that case when I
reenabled the building of the book. In fact, the .help files should in
my opinion, be singled out of the doc-building process, because they are
pretty independent. In fact, the only reason why they are built through
the src/doc directory is, because the sources are in
src/doc/htex/ug16.htex and the awk script and Makefile stanzas live
under src/doc. Eventually they go to
target/x86_64-linux-gnu/share/spadhelp.

In my opinion it would make sense to create a new directory
"src/spadhelp" and put there syscmd.awk and the Makefile:

===== src/spadhelp/Makefile ================
srcdir = ${fricas_src_srcdir}/doc
htexsrcdir = ${srcdir}/htex
helptargetdir = $(fricas_target_datadir)/spadhelp
UGSYSCMD2HELP = ${AWK} -f ${srcdir}/syscmd.awk

###################################################################
# Generate the .help file.
###################################################################
# ug16.htex contains documentation about system commands
stamp-ug16helpfiles:
${UGSYSCMD2HELP} ${htexsrcdir}/ug16.htex
${STAMP} $@

###################################################################
# The following targets only copy generated files to the target
# directory.
###################################################################
copy-helpfiles: stamp-ug16helpfiles
${MKDIR_P} ${helptargetdir}
cp *.help ${helptargetdir}
==================================

That would then be built unconditionally and my previous changes for the
generation of the .help files would be undone.

I am a bit hesitant to introduce a new src directory with only the build
scripts but no content (because that would still live under
src/doc/htex/ug16.htex). That is why I ask for you opinion.

Ralf

[Waldek Hebisch]

On Sun, Feb 26, 2023 at 09:40:42PM +0100, Ralf Hemmecke wrote:
> Hi Waldek,
>
> I looked a bit deeper into this issue of compilation with --with-x=no.
>
> The problem seems to be that I did not consider that case when I reenabled
> the building of the book. In fact, the .help files should in my opinion, be
> singled out of the doc-building process, because they are pretty
> independent. In fact, the only reason why they are built through the src/doc
> directory is, because the sources are in src/doc/htex/ug16.htex and the awk
> script and Makefile stanzas live under src/doc. Eventually they go to
> target/x86_64-linux-gnu/share/spadhelp.
>
> In my opinion it would make sense to create a new directory "src/spadhelp"

I have doubts about such split. Rather, I think that we should have
more fine grained control in Makefiles. In principle documentation
build should be independent of X. For example, in principle TeX version
of FriCAS Book should build without X. And one can imagine other formats
that should work without X. It is just current limitation that we need
X. And I dislike idea that we should re-organize source tree when/if
improved documentation build is possible. It makes sense to have
per-format build/target directories, but sources should have logical
organization independent of the format.

IMO right way is to always recurse to documentation subdirectory,
but configure hould pass info about X availability to documentation
Makefile. In documentation Makefile we can use conditionals to
enable only targets buildable without X. We already have logic
for pages depending on graphic (connection to X server). Such
logic should be more general.

--
Waldek Hebisch

[Ralf Hemmecke]

On 27.02.23 23:52, Waldek Hebisch wrote:
> IMO right way is to always recurse to documentation subdirectory,
> but configure hould pass info about X availability to documentation
> Makefile. In documentation Makefile we can use conditionals to
> enable only targets buildable without X. We already have logic
> for pages depending on graphic (connection to X server). Such
> logic should be more general.

Ok, that's what I wanted to hear and that is fine with me.

As far as I remember the html pages do not require X, but sphinx-doc,
however, building the book only works correctly, if I have the graphics.

For the book there would be two options.
1) do not allow to build the book if graphics cannot be generated
2) create a local version of the book without graphics

For simplicity, I am rather in favour of (1) since it is much easier to
just download book.pdf from github. I think, it is a waste of effort to
do (2).

Actually, I am not so clear with this X stuff. As far as I understand,
we need some X libraries to build the graphics subsystem and we need a
running X server to actually create the pictures.
In the unlikely case that someone has the libraries, but no running X
server, creating the book would also not work, right? Or would it by
using xvfb?

Anyhow, I think I set some variables in configure.ac and add the doc
directory unconditionally to the build, i.e. .help files. The book and
the html pages will only work by explicitly calling "cd src/doc; make
book.pdf" or "make doc" and fail gracefully if it is known from
configure time that they cannot be built.

Ralf