search

zowe / docs-site

Documentation for the Zowe project
https://docs.zowe.org/
Creative Commons Attribution 4.0 International
70 stars 133 forks source link

Download PDF and Navigate to Relevant Section #45

Closed adambattenburg closed 5 years ago

adambattenburg commented 6 years ago

When opening a PDF, we can direct the user to the relevant section using a link like https://zowe.github.io/docs-site/Zowe_User_Guide.pdf#page=5. It is also be possible to go to a section like "https://zowe.github.io/docs-site/Zowe_User_Guide.pdf#contents". However I haven't been able to manage this yet not understanding how the PDF is generated. I think I just have the wrong section names.

While we could go to page numbers, I'd like to avoid that and instead navigate to sections that are the same as the file name or Title. This might require making sure we have no duplicates in title names, but also might be less brittle in the long run.

This could then be placed in the page header along with 'Last Updated' and 'Edit Page'. Let me know what you think and maybe @nannanli you could investigate if we can link to specific sections of the doc instead of page numbers?

nannanli commented 6 years ago

Thanks Adam, I like this idea. Let me check if I understand what you're trying to do correctly. You are saying that we want to add something like Read this topic in PDF: readinpdf

When users open the link, they are directed to the same topic in the PDF file. Is this correct?

The PDF now is generated using DCS Oxygen Author. This tool converts MD to PDF by pulling content from a map https://github.com/zowe/docs-site/blob/master/docs/user-guide/Zowe_User_Guide.ditamap that lists all MD files to be converted. I'll investigate it it supports link to sections.

adambattenburg commented 6 years ago

Yes that was what I was thinking. I think it was something we had talked about before previously as an addition. Similar to what AWS has in their docs system.

I looked at the ditamap, and it seemed to provide what we needed, but none of the hrefs work. When you go into the PDF, you can right click the table of contents headers and find 'Copy Link Location' to see the real link location. An example is here.

If we can't make normal titles using Oxygen Author we can always try going to the page number directly. @PlutoZhang might be interested in this functionality for the next PDF generation tool that he is looking at.

PlutoZhang commented 6 years ago

@adambattenburg I like this idea, too. I will investigate this in the new PDF generation method.

nannanli commented 6 years ago

This is an example from AWS: https://docs.aws.amazon.com/machine-learning/latest/dg/step-2-create-a-datasource.html. By clicking the PDF icon, users can read the current topic in PDF.

The current way w use to generate PDF does not seem to support this. We might need an alternative way to generate PDF.

PlutoZhang commented 6 years ago

Possible solutions. As discussed, @jackjia-ibm could you help explore deeper and see if which could work with the current pipeline? Thanks!

  1. gitbook cli + Calibre: calibre for linux: https://calibre-ebook.com/download_linux o git clone the github repo and run one npm command and it's done o Local build o Open source o No extra numbering work needed, compared to Pandoc o ? PDF automation
  2. XSL stylesheets with Apache FOP, https://docs.aws.amazon.com/chime/latest/ag/what-is-chime.html
  3. Dita-ot.org https://www.dita-ot.org/
  4. Zapier: https://zapier.com/blog/markdown-html-export/ Jobs: Github MD —>Formatter to HTML —>Goggle Cloud Print to PDF

Optimal PDF:

  1. Format looks good: Titles/tables/graphics/code blocks are displayed correctly CSS/other format control file can be customized
  2. TOC generated The file to be used as the map to organize all the files, easy to maintain (in DCS PDF build option, we maintain another file .ditamap to generate the PDF; HTML TOC/nav is generated using config.js)
  3. Automated PDF build upon trigger condition Like the html build, html content refreshed when pull request is committed in Branch master
  4. Direct the user to the relevant section: One example: https://docs.aws.amazon.com/chime/latest/ag/what-is-chime.html
jackjia-ibm commented 5 years ago

After some investigation, I chosen dita-ot.org, which I believe it's the similar tool as before.

For directing user to the relevant section, after some research, I noticed it's a open feature request https://github.com/dita-ot/dita-ot/issues/1708. To achieve this, I need some time to learn how to create a dita-ot plugin to enhance the behavior.

So the coming Pull Request https://github.com/zowe/docs-site/pull/291 will be targeting to only solve the PDF generating task.