Opened 11 years ago

Closed 10 years ago

Last modified 10 years ago

#4460 closed enhancement (fixed)

[with patch, positive review] add link to PDF manuals in doc/html/index.html

Reported by: schilly Owned by: tba
Priority: minor Milestone: sage-4.1.1
Component: documentation Keywords:
Cc: Merged in: Sage 4.1.1.rc0
Authors: Mitesh Patel Reviewers: John Palmieri, Minh Van Nguyen
Report Upstream: Work issues:
Branch: Commit:
Dependencies: Stopgaps:

Description

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.

Attachments (4)

trac_4460_pdf_links.patch (9.7 KB) - added by mpatel 10 years ago.
Includes pdf.png
trac_4460-pdf_links_v2.patch (10.6 KB) - added by mpatel 10 years ago.
Apply only this patch.
trac_4460-pdf_links_v3.patch (11.6 KB) - added by mpatel 10 years ago.
Apply only this patch.
trac_4460-manifest.patch (773 bytes) - added by mvngu 10 years ago.
add doc/en/website/static/pdf.png to MANIFEST.in

Download all attachments as: .zip

Change History (24)

Changed 10 years ago by mpatel

Includes pdf.png

comment:1 Changed 10 years ago by mpatel

  • Summary changed from add link to PDF manuals in doc/html/index.html to [with patch, needs review] add link to PDF manuals in doc/html/index.html

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

comment:2 Changed 10 years ago by mpatel

  • Priority changed from critical to minor

comment:3 Changed 10 years ago by mpatel

  • Authors set to Mitesh Patel

comment:5 Changed 10 years ago by mpatel

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

comment:6 follow-up: Changed 10 years ago by jhpalmieri

  • Summary changed from [with patch, needs review] add link to PDF manuals in doc/html/index.html to [with patch, needs work] add link to PDF manuals in doc/html/index.html

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."

Changed 10 years ago by mpatel

Apply only this patch.

comment:7 in reply to: ↑ 6 Changed 10 years ago by mpatel

  • Summary changed from [with patch, needs work] add link to PDF manuals in doc/html/index.html to [with patch, needs review] add link to PDF manuals in doc/html/index.html

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

comment:8 Changed 10 years ago by jhpalmieri

  • Summary changed from [with patch, needs review] add link to PDF manuals in doc/html/index.html to [with patch, positive review] add link to PDF manuals in doc/html/index.html

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.

comment:9 Changed 10 years ago by mvngu

  • Reviewers set to John Palmieri

comment:10 Changed 10 years ago by mvngu

  • Merged in set to Sage 4.1.1.alpha1
  • Resolution set to fixed
  • Status changed from new to closed

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.

comment:11 Changed 10 years ago by mpatel

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.

Changed 10 years ago by mpatel

Apply only this patch.

comment:12 Changed 10 years ago by mpatel

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?

comment:13 follow-up: Changed 10 years ago by mvngu

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

comment:14 in reply to: ↑ 13 Changed 10 years ago by mpatel

Replying to 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.

comment:15 Changed 10 years ago by mpatel

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

Changed 10 years ago by mvngu

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

comment:16 follow-up: Changed 10 years ago by mvngu

  • Merged in Sage 4.1.1.alpha1 deleted
  • Resolution fixed deleted
  • Status changed from closed to reopened
  • Summary changed from [with patch, positive review] add link to PDF manuals in doc/html/index.html to [with patch, needs review] add link to PDF manuals in doc/html/index.html

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?

comment:17 Changed 10 years ago by jhpalmieri

  • Summary changed from [with patch, needs review] add link to PDF manuals in doc/html/index.html to [with patch, positive review] add link to PDF manuals in doc/html/index.html

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

comment:18 in reply to: ↑ 16 Changed 10 years ago by mpatel

Replying to 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.

comment:19 Changed 10 years ago by mvngu

  • Merged in set to Sage 4.1.1.rc0
  • Resolution set to fixed
  • Status changed from reopened to closed

Merged:

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

comment:20 Changed 10 years ago by mvngu

  • Reviewers changed from John Palmieri to John Palmieri, Minh Van Nguyen
Note: See TracTickets for help on using tickets.