<div dir="ltr"><br><div class="gmail_extra"><br><div class="gmail_quote">On Sun, Feb 5, 2017 at 4:54 PM, Ian Y. Choi <span dir="ltr"><<a href="mailto:ianyrchoi@gmail.com" target="_blank">ianyrchoi@gmail.com</a>></span> wrote:<br><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">Hello,<br>
<br>
Me and SeongSoo have been collaborating a lot to apply better customized styles<br>
to PDF documents from rst-based guide documents (spec is available at [1]).<br>
<br>
Applying styles from documents with a basic pdflatex theme (example: [2, 3, 4]) have not been easy for us.<br>
However, thanks to the new sphinx version support [5], lots of latest styling options described<br>
in Sphinx documentation [6] are now well-applicable to openstack-manuals!<br>
<br>
The draft PDF styling results are available at [7].<br>
You can check new PDF files by clicking "gate-openstack-manuals-tox-do<wbr>c-publish-checkbuild"<br>
and "(pdf)" links for arch-design, ha-guide, image-guide, and user-guide (for example: [8]).<br>
<br>
More detailed descriptions are available at Etherpad [9].<br>
<br>
I would like to ask team members to review the new draft PDF styling results,<br>
and if you are fine, then me and SeongSoo want to migrate current python and latex styling files<br>
into openstackdocstheme and then polish [7] to make use of a new openstackdocstheme<br>
with PDF theme & styles.<br>
<br>
Also, since I am not familiar with the following issues, please also share your idea & thoughts on:<br>
- In conf.py, version numbers are specified such as "0.0.1" and "0.9".<br>
Will it be so important for PDFs? I think just "master" or release names such as "Newton" and "Ocata"<br></blockquote><div><br></div><div>Depends on the type of guide. For admin guides and other openstack-manuals guides, the grouped release name is sufficient. However, for Client guides like python-openstackclient, that version number is crucial for bug reporting and what features are available in a release. If your PDF generation scope is for openstack-manuals, release names are fine. For number-relevant releases, please ensure the release number is used.</div><div> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">
would deliver more contextual meanings to document readers.<br>
- I suggest not to use chapter and section numbers for PDFs.<br>
Current rst documents are written for the best presentation with HTMLs but current chapter and section<br>
notations prevent PDFs from automatically parsing appropriate numbers. For example, [2-4] denote<br>
number "1" for "Abstract", "3" for "Appendix", and so on.<br></blockquote><div><br></div><div>I think that's fine. Page numbers are sufficient as is anything the parser gives us now.</div><div> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">
- Could somebody recommend to select open source font(s) suitable to the PDFs?<br>
<br>
<br></blockquote><div><br></div><div>I looked up the history and we had to choose open source fonts per language output. So test the font with translated docs also. We used to use <span style="font-size:12.8px">CartoGothic-Std for the English font. For Japanese it was </span><span style="font-size:12.8px">TakaoGothic </span><span class="gmail-il" style="font-size:12.8px;background-color:rgb(255,255,255)">font. The thread with a lot of info is here: <a href="http://lists.openstack.org/pipermail/openstack-docs/2013-May/001583.html">http://lists.openstack.org/pipermail/openstack-docs/2013-May/001583.html</a></span></div><div><span class="gmail-il" style="font-size:12.8px;background-color:rgb(255,255,255)"><br></span></div><div><span class="gmail-il" style="font-size:12.8px;background-color:rgb(255,255,255)">Nice work Ian, much appreciated.</span></div><div><span class="gmail-il" style="font-size:12.8px;background-color:rgb(255,255,255)">Anne</span></div><div> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">
With many thanks,<br>
<br>
/Ian<br>
<br>
[1] <a href="http://specs.openstack.org/openstack/docs-specs/specs/ocata/build-pdf-from-rst-guides.html" rel="noreferrer" target="_blank">http://specs.openstack.org/ope<wbr>nstack/docs-specs/specs/ocata/<wbr>build-pdf-from-rst-guides.html</a><br>
[2] <a href="http://docs.openstack.org/arch-design/ArchGuideRst.pdf" rel="noreferrer" target="_blank">http://docs.openstack.org/arch<wbr>-design/ArchGuideRst.pdf</a><br>
[3] <a href="http://docs.openstack.org/ha-guide/HAGuide.pdf" rel="noreferrer" target="_blank">http://docs.openstack.org/ha-g<wbr>uide/HAGuide.pdf</a><br>
[4] <a href="http://docs.openstack.org/draft/install-guide-ubuntu/InstallGuide.pdf" rel="noreferrer" target="_blank">http://docs.openstack.org/draf<wbr>t/install-guide-ubuntu/Install<wbr>Guide.pdf</a><br>
[5] <a href="https://review.openstack.org/#/c/419110/2/test-requirements.txt" rel="noreferrer" target="_blank">https://review.openstack.org/#<wbr>/c/419110/2/test-requirements.<wbr>txt</a><br>
[6] <a href="http://www.sphinx-doc.org/en/stable/latex.html" rel="noreferrer" target="_blank">http://www.sphinx-doc.org/en/s<wbr>table/latex.html</a><br>
[7] <a href="https://review.openstack.org/#/c/427826/" rel="noreferrer" target="_blank">https://review.openstack.org/#<wbr>/c/427826/</a><br>
[8] <a href="http://docs-draft.openstack.org/26/427826/13/check/gate-openstack-manuals-tox-doc-publish-checkbuild/d8ffd03//publish-docs/" rel="noreferrer" target="_blank">http://docs-draft.openstack.or<wbr>g/26/427826/13/check/gate-open<wbr>stack-manuals-tox-doc-publish-<wbr>checkbuild/d8ffd03//publish-do<wbr>cs/</a><br>
[9] <a href="https://etherpad.openstack.org/p/docs-build-pdf-from-rst-styling" rel="noreferrer" target="_blank">https://etherpad.openstack.org<wbr>/p/docs-build-pdf-from-rst-sty<wbr>ling</a><br>
<br>
______________________________<wbr>_________________<br>
OpenStack-docs mailing list<br>
<a href="mailto:OpenStack-docs@lists.openstack.org" target="_blank">OpenStack-docs@lists.openstack<wbr>.org</a><br>
<a href="http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs" rel="noreferrer" target="_blank">http://lists.openstack.org/cgi<wbr>-bin/mailman/listinfo/openstac<wbr>k-docs</a><br>
</blockquote></div><br><br clear="all"><div><br></div>-- <br><div class="gmail-m_-4310550665490738873gmail-m_3597669042479164930gmail_signature"><div dir="ltr"><div><div dir="ltr"><div dir="ltr"><div dir="ltr"><div><br></div><div>Read my blog: <a href="https://justwriteclick.com" target="_blank">justwrite.click</a></div><div>Subscribe to Docs|Code: <a href="http://docslikecode.com" target="_blank">docslikecode.com</a> </div></div></div></div></div></div></div>
</div></div>