add link to PDF manuals in doc/html/index.html

[haraldschilly]

Adding a link to the PDF versions of the manuals from the /html/index.html page. Both, useful locally and on the website. But I don't know how this page is generated (i get errors or nothing happens) and it isn't even under revision control. Here my improvised patch:

add in /sage/devel/doc-main/html/index.html.in at line 88:
------------
 <ul>
	    <li> <font size=+2><a href="../paper-$(PAPER)/" class="title">PDF Versions</a></font>
	      <br>
	  </ul>
-------------

An enhancement would be to link to each .pdf file directly, something like "link to html (PDF)" for each link.

Component: documentation

Author: Mitesh Patel

Reviewer: John Palmieri, Minh Van Nguyen

Merged: Sage 4.1.1.rc0

Issue created by migration from https://trac.sagemath.org/ticket/4460

[qed777]

Attachment: trac_4460_pdf_links.patch.gz

Includes pdf.png

[qed777]

comment:1

To generate the icon I used ImageMagick:

convert $SAGE_ROOT/local/share/moin/htdocs/applets/FCKeditor/editor/filemanager/browser/default/images/icons/pdf.gif $SAGE_ROOT/doc/en/website/static/pdf.png

[qed777]

Author: Mitesh Patel

[qed777]

comment:4

Note: attachment: trac_4460_pdf_links.patch depends on the trac_6485_website_links.patch at #6485.

[qed777]

comment:5

Can someone check the form and function of the updated page in multiple browsers on Mac OS X?

[jhpalmieri]

comment:6

This is with both Safari and Firefox on a Mac.

If I open the file SAGE_ROOT/devel/sage/doc/output/en/index.html, the links work fine.

On the other hand, if I click on the "Help" button from the notebook, then click on "Fast static versions of the Documentation", then the I see pdf links but they don't work: I get messages like "The resource /pdf/en/tutorial/SageTutorial.pdf cannot be found."

[qed777]

Apply only this patch.

[qed777]

comment:7

Attachment: trac_4460-pdf_links_v2.patch.gz

Replying to @jhpalmieri:

On the other hand, if I click on the "Help" button from the notebook, then click on "Fast static versions of the Documentation", then the I see pdf links but they don't work: I get messages like "The resource /pdf/en/tutorial/SageTutorial.pdf cannot be found."

Thanks very much for catching this. I think v2 covers both the static and offline docs.

Aside: In the drive for internationalization, perhaps we should instead map doc/common/output to, e.g., http://localhost:8000/doc/static and serve index.html as http://localhost:8000/doc/static/html/ + LANG + /index.html.

Correction: That should be

convert $SAGE_ROOT/local/share/moin/htdocs/applets/FCKeditor/editor/filemanager/browser/default/images/icons/pdf.gif $SAGE_ROOT/devel/sage/doc/en/website/static/pdf.png

[jhpalmieri]

comment:8

Looks good to me.

Aside: In the drive for internationalization, perhaps we should instead map doc/common/output to, e.g., http://localhost:8000/doc/static and serve index.html as http://localhost:8000/doc/static/html/ + LANG + /index.html.

I have no opinion about this, but if you want to do something about it, let's move it to another ticket.

[sagetrac-mvngu]

Reviewer: John Palmieri

[sagetrac-mvngu]

Merged: Sage 4.1.1.alpha1

[sagetrac-mvngu]

comment:10

Is there an option to turn off this linking to the PDF version of the documents from the HTML version? Currently, we distribute the standard documentation in two standalone formats: as PDF and as HTML; see

http://www.sagemath.org/help.html

The HTML version currently doesn't link to the PDF version, and I think there should be an option to stay with the current situation. If I understand the patch correctly, there is no option to turn off the linking to the PDF version (correct me if I'm wrong). That would be unfortunate as we would need to build both the HTML and PDF versions and distribute them as one single compressed (huge) file.

[qed777]

comment:11

That's a good idea. With the patch at #6187, it should be straightforward to add a command-line option that selects, in effect, a different layout for the "website" document. I'll try to implement this soon. I don't mind side-lining this ticket for another update and review.

[qed777]

Apply only this patch.

[qed777]

comment:12

Attachment: trac_4460-pdf_links_v3.patch.gz

Version 3 adds an option --no-pdf-links to the doc builder. Try

• sage -docbuild website html --no-pdf-links -S -a
• sage -docbuild website html -S -a
  Note: -S -a forces a rewrite.

Since #6187 awaits further inspection, I suggest that we keep waiting on this ticket. Meanwhile, feel free to populate the website's empty sidebar. Quick references?

[sagetrac-mvngu]

comment:13

The new patch trac_4460-pdf_links_v3.patch will need to be moved to another enhancement ticket.

[qed777]

comment:14

Replying to @sagetrac-mvngu:

The new patch trac_4460-pdf_links_v3.patch will need to be moved to another enhancement ticket.

No problem. I'll wait until there's more feedback on #6187.

[qed777]

comment:15

It seems that doc/en/website/static/pdf.png --- a new file --- from attachment: trac_4460-pdf_links_v2.patch is missing in v4.1.1.alpha1.

[sagetrac-mvngu]

add doc/en/website/static/pdf.png to MANIFEST.in

[sagetrac-mvngu]

Changed merged from Sage 4.1.1.alpha1 to none

[sagetrac-mvngu]

comment:16

Attachment: trac_4460-manifest.patch.gz

I'm reopening this ticket since the patch trac_4460-pdf_links_v2.patch resulted in a corrupted repository in Sage 4.1.1.alpha1. The patch trac_4460-manifest.patch should resolve this issue of corrupt repo. So apply patches in this order:

1. trac_4460-pdf_links_v2.patch
2. trac_4460-manifest.patch
   Only trac_4460-manifest.patch needs to be reviewed.

mpatel: Can you please open another ticket for the patch trac_4460-pdf_links_v3.patch and upload that patch there?

[jhpalmieri]

comment:17

Looks good. Sorry I missed this the first time around.

[qed777]

comment:18

Replying to @sagetrac-mvngu:

mpatel: Can you please open another ticket for the patch trac_4460-pdf_links_v3.patch and upload that patch there?

Absolutely. Please see #6653.

[sagetrac-mvngu]

Merged: Sage 4.1.1.rc0

[sagetrac-mvngu]

comment:19

Merged:

1. trac_4460-pdf_links_v2.patch
2. trac_4460-manifest.patch

[sagetrac-mvngu]

Changed reviewer from John Palmieri to John Palmieri, Minh Van Nguyen