<html><body><div style="color:#000; background-color:#fff; font-family:HelveticaNeue, Helvetica Neue, Helvetica, Arial, Lucida Grande, sans-serif;font-size:16px"><div>One question and one comment/question...</div><div id="yui_3_16_0_1_1436554797047_2132150"><br></div><div>I know of another include method, which is:</div><div id="yui_3_16_0_1_1436554797047_2132548"><br></div><div id="yui_3_16_0_1_1436554797047_2132551" dir="ltr">.. include:: /<path-from-top-of-repository>/<filename>.rst<br class=""></div><div id="yui_3_16_0_1_1436554797047_2132680" dir="ltr"><br></div><div id="yui_3_16_0_1_1436554797047_2132812" dir="ltr">What are the relative merits of this method to others?<br></div><div id="yui_3_16_0_1_1436554797047_2132810" dir="ltr"><br></div><div id="yui_3_16_0_1_1436554797047_2132940" dir="ltr">Also a caveat about reusing included files... If a file includes a referencing tag (that's an RST tag),</div><div id="yui_3_16_0_1_1436554797047_2133834" dir="ltr">it can only be included in one location in the repo or the build fails -- unless someone knows a clever</div><div id="yui_3_16_0_1_1436554797047_2133962" dir="ltr">work-around.</div><div dir="ltr"><br></div><div id="yui_3_16_0_1_1436554797047_2134221" dir="ltr">To explain, a file might code a section like:</div><div dir="ltr"><br></div><div id="yui_3_16_0_1_1436554797047_2134476" dir="ltr">.. _ntp-setup:</div><div id="yui_3_16_0_1_1436554797047_2134477" dir="ltr"><br></div><div id="yui_3_16_0_1_1436554797047_2134478" dir="ltr">Setting up NTP</div><div id="yui_3_16_0_1_1436554797047_2134737" dir="ltr">~~~~~~~~~~~~</div><div id="yui_3_16_0_1_1436554797047_2134738" dir="ltr"><br></div><div id="yui_3_16_0_1_1436554797047_2134993" dir="ltr">Another file could then reference this section as a link like this:</div><div dir="ltr"><br></div><div id="yui_3_16_0_1_1436554797047_2135121" dir="ltr">See :ref:`ntp-setup` for instructions.</div><div id="yui_3_16_0_1_1436554797047_2135123" dir="ltr"><br></div><div dir="ltr">I'm thinking that the NTP setup instructions are probably the same for Ubuntu, RHEL, et cetera, so this</div><div id="yui_3_16_0_1_1436554797047_2135125" dir="ltr">is a perfect candidate for having a common source file.</div><div dir="ltr"><br></div><div dir="ltr">I think it might work if the tag is coded in the include'ing file:</div><div id="yui_3_16_0_1_1436554797047_2135127" dir="ltr"><br></div><div dir="ltr">.. _ntp-setup-ubuntu:</div><div id="yui_3_16_0_1_1436554797047_2135129" dir="ltr"><br></div><div id="yui_3_16_0_1_1436554797047_2135131" dir="ltr"><include statement></div><div id="yui_3_16_0_1_1436554797047_2135133" dir="ltr"><br></div><div id="yui_3_16_0_1_1436554797047_2135135" dir="ltr">I don't know if this works with all include methods -- this should be considered because, I think as we move</div><div dir="ltr">forward, we will be needing to do more cross-referencing within the docs.</div><div id="yui_3_16_0_1_1436554797047_2135137" dir="ltr"><br></div><div dir="ltr">meg<br></div><div id="yui_3_16_0_1_1436554797047_2132149"><span></span></div><br> <blockquote style="border-left: 2px solid rgb(16, 16, 255); margin-left: 5px; margin-top: 5px; padding-left: 5px;"> <div style="font-family: HelveticaNeue, Helvetica Neue, Helvetica, Arial, Lucida Grande, sans-serif; font-size: 16px;"> <div style="font-family: HelveticaNeue, Helvetica Neue, Helvetica, Arial, Lucida Grande, sans-serif; font-size: 16px;"> <div dir="ltr"> <hr size="1"> <font face="Arial" size="2"> <b><span style="font-weight:bold;">From:</span></b> Andreas Jaeger <aj@suse.com><br> <b><span style="font-weight: bold;">To:</span></b> Matt Kassawara <mkassawara@gmail.com> <br><b><span style="font-weight: bold;">Cc:</span></b> "openstack-docs@lists.openstack.org" <Openstack-docs@lists.openstack.org> <br> <b><span style="font-weight: bold;">Sent:</span></b> Tuesday, July 14, 2015 7:11 AM<br> <b><span style="font-weight: bold;">Subject:</span></b> Re: [OpenStack-docs] RST include files - proposal forward<br> </font> </div> <div class="y_msg_container"><br>On 07/14/2015 03:51 PM, Matt Kassawara wrote:<br clear="none">> On includes...<br clear="none">><br clear="none">> Using includes within a guide make sense for repeating content. However,<br clear="none">> I'm not sure how much content meets this qualification outside of a few<br clear="none">> sections in the networking guide. The ability to reuse command (CLI)<br clear="none">> output increases consistency, reduces errors, and may also hasten<br clear="none">> updates when commands decide to change flags and/or output. On the other<br clear="none">> hand, it makes contributions (particularly for new folks) a bit more<br clear="none">> interesting. Let's decide if we want to use includes or not (perhaps try<br clear="none">> them in the networking guide?)... and if so, decide on how to make them<br clear="none">> work best technically.<br clear="none">><br clear="none">> On structure...<br clear="none">><br clear="none">> I prefer the single large HTML file with anchors for the following reasons:<br clear="none">><br clear="none">> 1) Easier navigation due to shallower structure (lack of pages mostly<br clear="none">> consisting of links to other sections).<br clear="none">> 2) Easier string searches with all content for a topic on a single page<br clear="none">> (EPPO?).<br clear="none"><br clear="none">But it covers many different topics, some not even really related <br clear="none">(besides it's all Identity)<br clear="none"><br clear="none">> 3) Fewer issues with deep linking by search engines and people to<br clear="none">> specific HTML filenames. Links to missing anchors simply redirect to the<br clear="none">> top of the page rather than 404.<br clear="none"><br clear="none"><br clear="none">So, what are you saying to my reviews?<br clear="none"><br clear="none">Those files should include the content directly instead of using the <br clear="none">include instruction?<br clear="none"><br clear="none">Or the files are fine as is?<br clear="none"><br clear="none">Thanks for looking into this,<br clear="none">Andreas<br clear="none"><br clear="none">> On Sun, Jul 12, 2015 at 3:34 AM, Andreas Jaeger <<a shape="rect" ymailto="mailto:aj@suse.com" href="mailto:aj@suse.com">aj@suse.com</a><br clear="none">> <mailto:<a shape="rect" ymailto="mailto:aj@suse.com" href="mailto:aj@suse.com">aj@suse.com</a>>> wrote:<br clear="none">><br clear="none">> Btw. I think we misused the include when converting. We now have<br clear="none">> files that are very large HTML files but were separate before.<br clear="none">><br clear="none">> Have a look at:<br clear="none">> <a shape="rect" href="https://review.openstack.org/#/c/200869/" target="_blank">https://review.openstack.org/#/c/200869/</a><br clear="none">> and compare the new content:<br clear="none">> <a shape="rect" href="http://docs-draft.openstack.org/69/200869/1/check/gate-openstack-manuals-tox-doc-publish-checkbuild/1c963f7//publish-docs/draft/admin-guide-cloud-rst/orchestration.html" target="_blank">http://docs-draft.openstack.org/69/200869/1/check/gate-openstack-manuals-tox-doc-publish-checkbuild/1c963f7//publish-docs/draft/admin-guide-cloud-rst/orchestration.html</a><br clear="none">><br clear="none">> the old docbook one:<br clear="none">> <a shape="rect" href="http://docs.openstack.org/admin-guide-cloud/content/ch_admin-openstack-orchestration.html" target="_blank">http://docs.openstack.org/admin-guide-cloud/content/ch_admin-openstack-orchestration.html</a><br clear="none">><br clear="none">> and the current converted one where everything is on a single page:<br clear="none">> <a shape="rect" href="http://docs.openstack.org/draft/admin-guide-cloud-rst/orchestration.html" target="_blank">http://docs.openstack.org/draft/admin-guide-cloud-rst/orchestration.html</a><br clear="none">><br clear="none">><br clear="none">> Similar check the Identity chapter in current RST where everything<br clear="none">> is a single page:<br clear="none">> <a shape="rect" href="http://docs.openstack.org/draft/admin-guide-cloud-rst/identity_management.html#use-trusts" target="_blank">http://docs.openstack.org/draft/admin-guide-cloud-rst/identity_management.html#use-trusts</a><br clear="none">><br clear="none">> and compare with the DocBook<br clear="none">> <a shape="rect" href="http://docs.openstack.org/admin-guide-cloud/content/ch-identity-mgmt-config.html" target="_blank">http://docs.openstack.org/admin-guide-cloud/content/ch-identity-mgmt-config.html</a><br clear="none">><br clear="none">> And then check my proposed change:<br clear="none">> <a shape="rect" href="https://review.openstack.org/200874" target="_blank">https://review.openstack.org/200874</a><br clear="none">><br clear="none">> and look at the html:<br clear="none">> <a shape="rect" href="http://docs-draft.openstack.org/74/200874/1/check/gate-openstack-manuals-tox-doc-publish-checkbuild/9ee3f7e//publish-docs/draft/admin-guide-cloud-rst/identity_management.html" target="_blank">http://docs-draft.openstack.org/74/200874/1/check/gate-openstack-manuals-tox-doc-publish-checkbuild/9ee3f7e//publish-docs/draft/admin-guide-cloud-rst/identity_management.html</a><br clear="none">><br clear="none">><br clear="none">> Andreas<br clear="none">> --<br clear="none">> Andreas Jaeger aj@{suse.com <<a shape="rect" href="http://suse.com/" target="_blank">http://suse.com</a>>,opensuse.org<br clear="none">> <<a shape="rect" href="http://opensuse.org/" target="_blank">http://opensuse.org</a>>} Twitter/Identica: jaegerandi<br clear="none">> SUSE LINUX GmbH, Maxfeldstr. 5, 90409 Nürnberg, Germany<br clear="none">> GF: Felix Imendörffer, Jane Smithard, Dilip Upmanyu, Graham Norton,<br clear="none">> HRB 21284 (AG Nürnberg)<br clear="none">> GPG fingerprint = 93A3 365E CE47 B889 DF7F FED1 389A 563C C272<br clear="none">> A126<br clear="none">><br clear="none">><br clear="none">> _______________________________________________<br clear="none">> OpenStack-docs mailing list<br clear="none">> <a shape="rect" ymailto="mailto:OpenStack-docs@lists.openstack.org" href="mailto:OpenStack-docs@lists.openstack.org">OpenStack-docs@lists.openstack.org</a><br clear="none">> <mailto:<a shape="rect" ymailto="mailto:OpenStack-docs@lists.openstack.org" href="mailto:OpenStack-docs@lists.openstack.org">OpenStack-docs@lists.openstack.org</a>><br clear="none">> <a shape="rect" href="http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs" target="_blank">http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs</a><br clear="none">><br clear="none">><br clear="none">><br clear="none">><br clear="none">> _______________________________________________<br clear="none">> OpenStack-docs mailing list<br clear="none">> <a shape="rect" ymailto="mailto:OpenStack-docs@lists.openstack.org" href="mailto:OpenStack-docs@lists.openstack.org">OpenStack-docs@lists.openstack.org</a><br clear="none">> <a shape="rect" href="http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs" target="_blank">http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs</a><div class="qtdSeparateBR"><br><br></div><div class="yqt1004037619" id="yqtfd93492"><br clear="none">><br clear="none"><br clear="none"><br clear="none">-- <br clear="none"> Andreas Jaeger aj@{suse.com,opensuse.org} Twitter/Identica: jaegerandi<br clear="none"> SUSE LINUX GmbH, Maxfeldstr. 5, 90409 Nürnberg, Germany<br clear="none"> GF: Felix Imendörffer, Jane Smithard, Dilip Upmanyu, Graham Norton,<br clear="none"> HRB 21284 (AG Nürnberg)<br clear="none"> GPG fingerprint = 93A3 365E CE47 B889 DF7F FED1 389A 563C C272 A126<br clear="none"><br clear="none"><br clear="none">_______________________________________________<br clear="none">OpenStack-docs mailing list<br clear="none"><a shape="rect" ymailto="mailto:OpenStack-docs@lists.openstack.org" href="mailto:OpenStack-docs@lists.openstack.org">OpenStack-docs@lists.openstack.org</a><br clear="none"><a shape="rect" href="http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs" target="_blank">http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs</a></div><br><br></div> </div> </div> </blockquote> </div></body></html>