Opened 14 years ago

Closed 13 years ago

Last modified 13 years ago

#4460 closed enhancement (fixed)

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

Reported by: Harald 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: N/A Work issues:
Branch: Commit:
Dependencies: Stopgaps:

Status badges

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 Mitesh Patel 13 years ago.
Includes pdf.png
trac_4460-pdf_links_v2.patch (10.6 KB) - added by Mitesh Patel 13 years ago.
Apply only this patch.
trac_4460-pdf_links_v3.patch (11.6 KB) - added by Mitesh Patel 13 years ago.
Apply only this patch.
trac_4460-manifest.patch (773 bytes) - added by Minh Van Nguyen 13 years ago.
add doc/en/website/static/pdf.png to MANIFEST.in

Download all attachments as: .zip

Change History (24)

Changed 13 years ago by Mitesh Patel

Attachment: trac_4460_pdf_links.patch added

Includes pdf.png

comment:1 Changed 13 years ago by Mitesh Patel

Summary: add link to PDF manuals in doc/html/index.html[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 13 years ago by Mitesh Patel

Priority: criticalminor

comment:3 Changed 13 years ago by Mitesh Patel

Authors: Mitesh Patel

comment:5 Changed 13 years ago by Mitesh Patel

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

comment:6 Changed 13 years ago by John Palmieri

Summary: [with patch, needs review] add link to PDF manuals in doc/html/index.html[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 13 years ago by Mitesh Patel

Apply only this patch.

comment:7 in reply to:  6 Changed 13 years ago by Mitesh Patel

Summary: [with patch, needs work] add link to PDF manuals in doc/html/index.html[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 13 years ago by John Palmieri

Summary: [with patch, needs review] add link to PDF manuals in doc/html/index.html[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 13 years ago by Minh Van Nguyen

Reviewers: John Palmieri

comment:10 Changed 13 years ago by Minh Van Nguyen

Merged in: Sage 4.1.1.alpha1
Resolution: fixed
Status: newclosed

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 13 years ago by Mitesh Patel

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 13 years ago by Mitesh Patel

Apply only this patch.

comment:12 Changed 13 years ago by Mitesh Patel

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 Changed 13 years ago by Minh Van Nguyen

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 13 years ago by Mitesh Patel

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 13 years ago by Mitesh Patel

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 13 years ago by Minh Van Nguyen

Attachment: trac_4460-manifest.patch added

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

comment:16 Changed 13 years ago by Minh Van Nguyen

Merged in: Sage 4.1.1.alpha1
Resolution: fixed
Status: closedreopened
Summary: [with patch, positive review] add link to PDF manuals in doc/html/index.html[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 13 years ago by John Palmieri

Summary: [with patch, needs review] add link to PDF manuals in doc/html/index.html[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 13 years ago by Mitesh Patel

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 13 years ago by Minh Van Nguyen

Merged in: Sage 4.1.1.rc0
Resolution: fixed
Status: reopenedclosed

Merged:

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

comment:20 Changed 13 years ago by Minh Van Nguyen

Reviewers: John PalmieriJohn Palmieri, Minh Van Nguyen
Note: See TracTickets for help on using tickets.