<html>
<head>
<meta content="text/html; charset=utf-8" http-equiv="Content-Type">
</head>
<body bgcolor="#FFFFFF" text="#000000">
<div class="moz-cite-prefix">Thanks all for kind comments!<br>
<br>
Now I have divided into three different groups to complete the
spec in Ocata cycle:<br>
<br>
1. Moving current proposed LaTeX style to openstackdocstheme<br>
: <a class="moz-txt-link-freetext" href="https://review.openstack.org/#/c/430263/">https://review.openstack.org/#/c/430263/</a><br>
<br>
- After then, releasing a new version for openstackdocstheme might
be needed to apply into the third group.<br>
<br>
2. Using Liberation font as English PDF documents<br>
: <a class="moz-txt-link-freetext" href="https://review.openstack.org/#/c/430549/">https://review.openstack.org/#/c/430549/</a><br>
<br>
- I have seen
<a class="moz-txt-link-freetext" href="http://git.openstack.org/cgit/openstack/clouddocs-maven-plugin/log/src/main/resources/fonts">http://git.openstack.org/cgit/openstack/clouddocs-maven-plugin/log/src/main/resources/fonts</a><br>
, but there is no information why CartoGothic font was selected
on there.<br>
IMO configuring different fonts for translated PDFs would be
possible, but I would like to<br>
implement this as a next step, since there might be some more
consideration to fully implement this.<br>
(Writing a new spec for Pike cycle would be a good idea I
think.)<br>
<br>
3. Applying LaTeX style using openstackdocstheme<br>
: <a class="moz-txt-link-freetext" href="https://review.openstack.org/#/c/427826/">https://review.openstack.org/#/c/427826/</a> will be adjusted after
merging the first patch.<br>
<br>
- Current is WIP and I think it would be nice to remove WIP after
the new version of openstackdocstheme will be released<br>
and the patch will make use of the new version of
openstackdocstheme.<br>
- Some (e.g., a few cases for too many characters in a line) might
be enhanced by patching on the 1st group,<br>
while others would be enhanced by adding more concise directives
in each rst document<br>
(e.g., tabularcolumns directive).<br>
<br>
The patches in three groups are somewhat inter-related, and also
reviewing them<br>
with different perspectives like tooling, styling, and UXs would
make PDF implementation more flawless :)<br>
<br>
<br>
Anne Gentle wrote on 2/7/2017 11:31 PM:<br>
</div>
<blockquote
cite="mid:CAD0KtVHwqs7JHAOaY-RCKwBNED0tSMjAOsU1K9p8UDvswp_h9g@mail.gmail.com"
type="cite">
<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 moz-do-not-send="true"
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>
</div>
</blockquote>
<br>
+1<br>
I have thought just for install-guides and network-guides, but yes,
the implementation method can be easily extended<br>
to api-site and client guides. Fortunately, the variation can be
accomplished easily by just changing "version" variable in conf.py!<br>
<br>
<blockquote
cite="mid:CAD0KtVHwqs7JHAOaY-RCKwBNED0tSMjAOsU1K9p8UDvswp_h9g@mail.gmail.com"
type="cite">
<div dir="ltr">
<div class="gmail_extra">
<div class="gmail_quote">
<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
moz-do-not-send="true"
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 moz-do-not-send="true"
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 moz-do-not-send="true"
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 moz-do-not-send="true"
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 moz-do-not-send="true"
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 moz-do-not-send="true"
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 moz-do-not-send="true"
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 moz-do-not-send="true"
href="https://review.openstack.org/#/c/427826/"
rel="noreferrer" target="_blank">https://review.openstack.org/#<wbr>/c/427826/</a><br>
[8] <a moz-do-not-send="true"
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 moz-do-not-send="true"
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 moz-do-not-send="true"
href="mailto:OpenStack-docs@lists.openstack.org"
target="_blank">OpenStack-docs@lists.openstack<wbr>.org</a><br>
<a moz-do-not-send="true"
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 moz-do-not-send="true"
href="https://justwriteclick.com"
target="_blank">justwrite.click</a></div>
<div>Subscribe to Docs|Code: <a
moz-do-not-send="true"
href="http://docslikecode.com" target="_blank">docslikecode.com</a> </div>
</div>
</div>
</div>
</div>
</div>
</div>
</div>
</div>
</blockquote>
<p><br>
</p>
</body>
</html>