Open Stack

On 06/19/2015 02:36 PM, Andreas Jaeger wrote:
> With DocBook, we had often included one file from another - and used
> that included file only in a single place. So, there was no reason to do
> it from an editors point of view, just splitting of content.
>
> Looking at https://review.openstack.org/#/c/192575/ I wonder what's the
> right thing to do. The included file is not mentioned in a table of
> contents and thus we normally use ":orphan:" but this does not work
> here, so a hidden toctable is used.
>
> BUT why should we split this up in several files at all? If there's a
> toc table used - or the file is used in several places -, splitting it
> up is fine but just for inclusion I see no need for separate files.
>
> Or is there a preference for how large files are and how to split them up?
>
> Is there any guidance we want to follow for file splits like these?
>
> Looking at the :orphan:/hidden toctable constructs, I'm against file
> splits and therefore ask to see whether we can reach some consensus that
> I then follow in further reviews,

Another example with the same problem:

https://review.openstack.org/#/c/193518/2/doc/admin-guide-cloud-rst/source/blockstorage.rst

Andreas
-- 
  Andreas Jaeger aj@{suse.com,opensuse.org} Twitter/Identica: jaegerandi
   SUSE LINUX GmbH, Maxfeldstr. 5, 90409 Nürnberg, Germany
    GF: Felix Imendörffer, Jane Smithard, Dilip Upmanyu, Graham Norton,
        HRB 21284 (AG Nürnberg)
     GPG fingerprint = 93A3 365E CE47 B889 DF7F  FED1 389A 563C C272 A126