Documentation indicates PDFs even if they are not made.

[David Kirkby]

The home page for the documentation has links to the Tutorial, FAQ,
Developer's Guide, Reference Manual etc in both HTML and PDF format.
But unless the PDF docs are built, the links are broken. So for my
installation, the homepage (HTML) is

/export/home/drkirkby/sage-4.6.2.rc0/devel/sage-main/doc/output/html/en/index.html

but has links to all these non-existent PDF

/export/home/drkirkby/sage-4.6.2.rc0/devel/sage-main/doc/output/pdf/en/tutorial/SageTutorial.pdf
/export/home/drkirkby/sage-4.6.2.rc0/devel/sage-main/doc/output/pdf/en/faq/faq.pdf
/export/home/drkirkby/sage-4.6.2.rc0/devel/sage-main/doc/output/pdf/en/constructions/constructions.pdf
/export/home/drkirkby/sage-4.6.2.rc0/devel/sage-main/doc/output/pdf/en/thematic_tutorials/thematic_tutorials.pdf
/export/home/drkirkby/sage-4.6.2.rc0/devel/sage-main/doc/output/pdf/en/developer/developer.pdf

This does not exactly give a good impression of Sage. People will
click a PDF, and get a message like

"File not found
Firefox can't find the file at
/export/home/drkirkby/sage-4.6.2.rc0/devel/sage-main/doc/output/pdf/en/faq/faq.pdf"

I was wondering if it would be possible to have a default PDF file,
which indicated what were the necessary steps to generate the real PDF
files.

Or perhaps "sage-4.6.2.rc0/devel/sage-main/doc/output/html/en/index.html"
has a note by the PDFs to indicate they will not exist unless they
have been built.

Dave

[Dr. David Kirkby]

On 02/20/11 04:05 AM, Minh Nguyen wrote:
> Hi David,

>
> On Sun, Feb 20, 2011 at 9:06 AM, David Kirkby<david....@onetel.net> wrote:
>> I was wondering if it would be possible to have a default PDF file,
>> which indicated what were the necessary steps to generate the real PDF
>> files.
>

> By default I build the HTML documentation without generating the links
> to the PDF version:
>
> ./sage -docbuild --no-pdf-links all html
>
> This is exactly what I usually do for the online documentation on the
> Sage website. An option is to patch the Makefile under SAGE_ROOT so
> you would get
>
> doc-html: build # (already) indirectly depends on $(PIPE)
> $(PIPE) "./sage -docbuild --no-pdf-link all html
> $(SAGE_DOCBUILD_OPTS) 2>&1" "tee -a dochtml.log"
>

That patch would seem sensible to me, as long as building the pdf docs remade
the HTML files with the links in.

The current situation, where "make" (with no arguments) produces broken links is
far from optimal.

--
A: Because it messes up the order in which people normally read text.
Q: Why is top-posting such a bad thing?
A: Top-posting.
Q: What is the most annoying thing in e-mail?

Dave