<div dir="ltr">Good Saturday to everyone!<div><br></div><div>Thanks Andreas for opening this topic. And thanks much Meg for such a detailed answer!</div><div><br></div><div>I agree with Meg here + another argument to have small children files that are logical sub-sections of 1 chapter: it's much easier to review and merge these in comparison with 200-300 lines' looong memoirs. I prefer files no longer than 100-150 lines. But I will gladly hear out other ideas on this matter. </div><div><br></div><div>Best</div><div>Lena</div><div><div class="gmail_extra"><br><div class="gmail_quote">On Sat, Jun 20, 2015 at 3:00 PM, <span dir="ltr"><<a href="mailto:openstack-docs-request@lists.openstack.org" target="_blank">openstack-docs-request@lists.openstack.org</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">Send OpenStack-docs mailing list submissions to<br>
<a href="mailto:openstack-docs@lists.openstack.org" target="_blank">openstack-docs@lists.openstack.org</a><br>
<br>
To subscribe or unsubscribe via the World Wide Web, visit<br>
<a href="http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs" rel="noreferrer" target="_blank">http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs</a><br>
or, via email, send a message with subject or body 'help' to<br>
<a href="mailto:openstack-docs-request@lists.openstack.org" target="_blank">openstack-docs-request@lists.openstack.org</a><br>
<br>
You can reach the person managing the list at<br>
<a href="mailto:openstack-docs-owner@lists.openstack.org" target="_blank">openstack-docs-owner@lists.openstack.org</a><br>
<br>
When replying, please edit your Subject line so it is more specific<br>
than "Re: Contents of OpenStack-docs digest..."<br>
<br>
<br>
Today's Topics:<br>
<br>
1. Re: RST conversion and file splits ? (Meg McRoberts)<br>
<br>
<br>
----------------------------------------------------------------------<br>
<br>
Message: 1<br>
Date: Fri, 19 Jun 2015 20:59:19 +0000 (UTC)<br>
From: Meg McRoberts <<a href="mailto:dreidellhasa@yahoo.com" target="_blank">dreidellhasa@yahoo.com</a>><br>
To: Andreas Jaeger <<a href="mailto:aj@suse.com" target="_blank">aj@suse.com</a>>,<br>
"<a href="mailto:openstack-docs@lists.openstack.org" target="_blank">openstack-docs@lists.openstack.org</a>"<br>
<<a href="mailto:openstack-docs@lists.openstack.org" target="_blank">openstack-docs@lists.openstack.org</a>><br>
Subject: Re: [OpenStack-docs] RST conversion and file splits ?<br>
Message-ID:<br>
<<a href="mailto:1002285246.2547175.1434747559361.JavaMail.yahoo@mail.yahoo.com" target="_blank">1002285246.2547175.1434747559361.JavaMail.yahoo@mail.yahoo.com</a>><br>
Content-Type: text/plain; charset="utf-8"<br>
<br>
I do not thoroughly grok the intricacies of toctree --I just try to follow whatsomeone else does and hope it doesn't blow up on me ;-)<br>
However, it sounds like you are musing about issues of source file structureand I have been thinking about that a bit.? It sounds like you are thinking abouthaving one big file per "topic".? I have worked with people who argue that nodoc source file should have more than one heading in it -- each subsectiongets its own file.? My own preferences fall somewhere in the middle, but findingthe "sweet spot" between the two is non-trivial.<br>
The great advantage of having smaller files is that different people can work ondifferent sections at the same time without causing horrific 6-way-merge scenarios.For example, in the new HA Guide, we have a topic about configuring the controllernode for high availability.? This has subtopics for pacemaker/corosync, mysql/galera, rabbitmq,<br>
HAProxy, keystone, et cetera.? The writers and reviewers for each of these subsectionsare often different people, so having those subtopics in different files that are includedin the larger topic file has definite advantages.<br>
I would advocate a less-flat directory structure for the source files.? Our current practiceseems to be to give a common "front-end" to all the subfiles for a topic, which causessome really long file names; for example:<br>
???? controller-ha.rst???? controller-ha-pacemaker.rst???? controller-ha-galera.rst???? controller-ha-rabbitmq.rst<br>
???? controller-ha-haproxy.rst???? et cetera<br>
It also makes for a very cluttered source directory.? Things would be cleaner if we hadonly the controller-ha.rst file in the source directory, with a controller subdirectory thathad files named pacemaker.rst, galera.rst, rabbitmq.rst, haproxy.rst...<br>
As appropriate, the subdirectory might have a subdirectory.? For example, the galerasubtopic might have separate sections for MySQL and MariaDB and maybe anotherdatabase or two.? Different people might work on different database options, so havinga galera subdirectory with different files for the different database architectures makessense.<br>
On the other hand, the haproxy subtopic might have sections for install, configure, verify,launch.? I don't see much advantage in breaking those up into separate files, although Iknow some people who would advocate for that.<br>
<br>
In addition to breaking the files up for parallel development, well-chosen discrete files cansimplify restructuring the material -- rather than having to yank 75 lines of doc source fromone file and insert it into another, you can just move the inclusion line from one topic fileto another and voila!<br>
What does everyone else think?meg<br>
<br>
<br>
From: Andreas Jaeger <<a href="mailto:aj@suse.com" target="_blank">aj@suse.com</a>><br>
To: "<a href="mailto:openstack-docs@lists.openstack.org" target="_blank">openstack-docs@lists.openstack.org</a>" <<a href="mailto:openstack-docs@lists.openstack.org" target="_blank">openstack-docs@lists.openstack.org</a>><br>
Sent: Friday, June 19, 2015 11:40 AM<br>
Subject: Re: [OpenStack-docs] RST conversion and file splits ?<br>
<br>
On 06/19/2015 02:36 PM, Andreas Jaeger wrote:<br>
> With DocBook, we had often included one file from another - and used<br>
> that included file only in a single place. So, there was no reason to do<br>
> it from an editors point of view, just splitting of content.<br>
><br>
> Looking at <a href="https://review.openstack.org/#/c/192575/" rel="noreferrer" target="_blank">https://review.openstack.org/#/c/192575/</a> I wonder what's the<br>
> right thing to do. The included file is not mentioned in a table of<br>
> contents and thus we normally use ":orphan:" but this does not work<br>
> here, so a hidden toctable is used.<br>
><br>
> BUT why should we split this up in several files at all? If there's a<br>
> toc table used - or the file is used in several places -, splitting it<br>
> up is fine but just for inclusion I see no need for separate files.<br>
><br>
> Or is there a preference for how large files are and how to split them up?<br>
><br>
> Is there any guidance we want to follow for file splits like these?<br>
><br>
> Looking at the :orphan:/hidden toctable constructs, I'm against file<br>
> splits and therefore ask to see whether we can reach some consensus that<br>
> I then follow in further reviews,<br>
<br>
Another example with the same problem:<br>
<br>
<a href="https://review.openstack.org/#/c/193518/2/doc/admin-guide-cloud-rst/source/blockstorage.rst" rel="noreferrer" target="_blank">https://review.openstack.org/#/c/193518/2/doc/admin-guide-cloud-rst/source/blockstorage.rst</a><br>
<br>
<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>
<br>
_______________________________________________<br>
OpenStack-docs mailing list<br>
<a href="mailto:OpenStack-docs@lists.openstack.org" target="_blank">OpenStack-docs@lists.openstack.org</a><br>
<a href="http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs" rel="noreferrer" target="_blank">http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs</a><br>
<br>
<br>
<br>
-------------- next part --------------<br>
An HTML attachment was scrubbed...<br>
URL: <<a href="http://lists.openstack.org/pipermail/openstack-docs/attachments/20150619/10e0cb74/attachment-0001.html" rel="noreferrer" target="_blank">http://lists.openstack.org/pipermail/openstack-docs/attachments/20150619/10e0cb74/attachment-0001.html</a>><br>
<br>
------------------------------<br>
<br>
_______________________________________________<br>
OpenStack-docs mailing list<br>
<a href="mailto:OpenStack-docs@lists.openstack.org" target="_blank">OpenStack-docs@lists.openstack.org</a><br>
<a href="http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs" rel="noreferrer" target="_blank">http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs</a><br>
<br>
<br>
End of OpenStack-docs Digest, Vol 36, Issue 48<br>
**********************************************<br>
</blockquote></div><br><br clear="all"><div><br></div>-- <br><div><div dir="ltr"><div>Best regards,</div>Olena Logvinova,<div>Technical Writer | Mirantis, Kharkiv | 38, Lenin av., Kharkiv</div><div><a href="mailto:ologvinova@mirantis.com" style="color:rgb(17,85,204)" target="_blank">ologvinova@mirantis.com</a> | <a href="tel:%2B380950903196" value="+380669377102" style="color:rgb(17,85,204)" target="_blank">+380950903196</a></div></div></div>
</div></div></div>