Open Stack

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,

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