<div dir="ltr"><br><div class="gmail_extra"><br><div class="gmail_quote">On Sat, Jul 11, 2015 at 2:35 PM, Andreas Jaeger <span dir="ltr"><<a href="mailto:aj@suse.com" target="_blank">aj@suse.com</a>></span> wrote:<br><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex"><span class="">On 07/11/2015 08:05 PM, Anne Gentle wrote:<br>
</span><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex"><span class="">
<br>
<br>
On Sat, Jul 11, 2015 at 12:56 PM, Andreas Jaeger <<a href="mailto:aj@suse.com" target="_blank">aj@suse.com</a><br></span><span class="">
<mailto:<a href="mailto:aj@suse.com" target="_blank">aj@suse.com</a>>> wrote:<br>
<br>
So far, we have included RST files with<br>
:include: some-file.rst<br>
<br>
and then added the file to a hidden toctree.<br>
<br>
I propose - as mentioned by somebody else previously - to use the<br>
following practice:<br>
<br>
* include files end with .txt<br>
<br>
That's all. Since sphinx ignores .txt files, we do not need to add<br>
any hidden toctree at all...<br>
<br>
<br>
One potential benefit to keeping .rst is that they render okay (not<br>
great, I know) on GitHub itself. Basically .txt files with RST markup<br>
don't render at all.<br>
</span></blockquote>
<br>
With all these hidden tocentries, I consider inclusion of the RST some ugliness which we don't get with TXT files. It also makes it clear that TXT are included files.</blockquote><div><br></div><div>Yep, I know what ugliness you mean. :)</div><div> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex"><span class=""><br>
<br>
<br>
<blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex">
I've seen both practices so we should discuss, adopt one and stick with it.<br>
Thanks for bringing it up Andreas!<br>
</blockquote>
<br></span>
Btw. since we do not have <section> but headings with specific markup for each level, an include file with headings might not be reused in other places - only if it's at the same level of headings.<br></blockquote><div><br></div><div>By "might not be reused" do you mean should not be reused at all, or only reused if all the headers in the file will be at the same heading level in each inclusion?</div><div><br></div><div>I haven't studied the plans for the user guide/ admin guides re-works to know if there will be much of this.</div><div> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex">
<br>
Thus, my preference would even be to avoid includes *unless* we need them for duplicate content. But so far I haven't seen any buy-in on this, so propose the above.</blockquote><div><br></div><div>So, best practice, stop duplicating content? Or avoid includes always? I'd lean towards flatter less book-ish structures myself but I don't know how things are looking for the re-architecting. Looking at <a href="http://specs.openstack.org/openstack/docs-specs/specs/liberty/reorganise-user-guides.html">http://specs.openstack.org/openstack/docs-specs/specs/liberty/reorganise-user-guides.html</a> we may need to avoid includes?</div><div><br></div><div>Those are my questions for now, thanks for the quick response.</div><div>Anne<br></div><div> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex"><div class=""><div class="h5"><br>
<br>
Andreas<br>
-- <br>
Andreas Jaeger aj@{<a href="http://suse.com" rel="noreferrer" target="_blank">suse.com</a>,<a href="http://opensuse.org" rel="noreferrer" target="_blank">opensuse.org</a>} Twitter/Identica: jaegerandi<br>
SUSE LINUX GmbH, Maxfeldstr. 5, 90409 Nürnberg, Germany<br>
GF: Felix Imendörffer, Jane Smithard, Dilip Upmanyu, Graham Norton,<br>
HRB 21284 (AG Nürnberg)<br>
GPG fingerprint = 93A3 365E CE47 B889 DF7F FED1 389A 563C C272 A126<br>
<br>
</div></div></blockquote></div><br><br clear="all"><div><br></div>-- <br><div class="gmail_signature"><div dir="ltr"><div>Anne Gentle</div><div>Rackspace</div><div>Principal Engineer</div><div><a href="http://www.justwriteclick.com" target="_blank">www.justwriteclick.com</a></div></div></div>
</div></div>