On Wed, 18 Dec 2024 20:37:13 +0000 (UTC)
Joseph Myers <josmy...@redhat.com> wrote:
> So make sure your patches include the changes required to
> update_web_docs_git to install HTML and PDF versions of those man
> pages, and point to somewhere we can see the formatted versions.
> That will then provide a way to compare with other manuals.
Before I wander into update_web_docs_git, let me apprise you of what we
have so far.
In Make-lang.in, I added targets to build html and pdf versions of the
man pages. I also added cobol.srchtml etc. to (I hope) support bringing
the generated documentation into the source tree, so that tarballs
don't require any tools to get the documentation.
They require mandoc(1) for html and groff(1) for PDF. (Old
versions of groff did not generate PDF directly. I don't remember
exactly, but the feature was introduced between groff 19 and 23.)
I find the HTML serviceable. It could use some css love, but are
correct and presentable.
I added install targets:
cobol.install-pdf: installdirs gcobol.pdf gcobol-io.pdf
mkdir -p $(DESTDIR)$(datadir)/gcobol/pdf
$(INSTALL_DATA) gcobol.pdf gcobol-io.pdf $(DESTDIR)
$(datadir)/gcobol/pdf/
cobol.install-html: installdirs gcobol.html gcobol-io.html
$(INSTALL_DATA) gcobol.html gcobol-io.html $(DESTDIR)$(htmldir)/
It's not clear to me there should be an install target for PDF because
there's no pdfdir variable defined (akin to htmldir).
Looking at update_web_docs_git, it appears I should recapitulate
the same work under the loop after:
> # Now convert the relevant files from texi to HTML, PDF and
> # PostScript.
to copy the gcobol pages to the relevant directories before the files
are renamed and copied.
I guess when this script runs, nothing has been configured and no
Makefiles exist. I know how to write a shell script, but have no idea
how to test any changes I make to this script. I don't know whether to
assume mandoc & troff are installed and functional, or what to do if
not. From what I see, I should tack on "|| true" to anything that
might fail.
Looking forward to your advice.
--jkl
