On 7 March 2014 18:02, Jens Getreu <[email protected]> wrote: > Hello Dan, > > On Monday, 3 March 2014 00:59:46 UTC+2, Dan Allen wrote: >> >> ... >> >> - the document has to be parsed, which is not appropriate at this point in >> the processor (we have to consider comment lines, attribute entries, etc) >> both above & below >> - the document may not have level 0 as its starting section title, but >> could still be a subdocument >> - we might be in a literal context, for which the preprocessor is not >> aware >> - we break compatibility with AsciiDoc Python severely, with no way to >> emulate the behavior there >> - ... > > Yes very good arguments. You convinced me: there should be a second command > besides "include". >
Dan and Jens, sorry I thought this was so obvious that I didn't mention it :) The semantics of "textual include" and "included document where some attributes are inherited and some are not" are two very different things, so of course there needs to be a new feature. >> >> I definitely agree there is a need for the subdocuments feature. I also >> believe that it should be implemented as a block macro. >> >> As for the name, includedocument is far too verbose. I think subdocument >> or just subdoc is sufficient. > > I would like to avoid the term "subdocument" at all. The term was > established with MSWord. There master- and subdocuments have special > characteristics, which make them distinguishable. Its sad to let other wrongly implemented programs drive our naming, I also would have chosen "subdoc" as the included file becomes a subdocument of the one including it, but really I don't care so long as its short and immediately understandable, remember Asciidoc syntax is not a programming language, its meant to be a readable document. > > To take plain advantage of the new feature there should be no special > requirements to our subdocuments. At my point view the most important design > goal is: Every asciidoc document can be stand alone and subdocument at the > same time. It enables us inter alia to generate automatically collections of > individual reports, collections of student exercises etc. Yes, agree that ideally there should be no special requirements of documents which can be used as subdocuments, but there will probably be some. For instance if a subdocument explicitly sets an attribute then that can't be overridden from the master document. These sorts of requirements are more likely to be in the form of standard idioms than explicit markup (as much as I hate hidden semantics). > > From this it follows that documents and subdocumets do not differ at all. > This is why I prefer to avoid the term "subdocument" here and rather would > liked to use "included document". The concept differs from what had been > introduced with MSWord many years ago. > > If "includedocument" is too long for you, what about "includedoc" ? > > >> >> I want to emphasize that it's possible to start prototyping this feature >> today using a block macro extension. I'd like it to live as an extension >> while we flesh it out and bring it into core once we've got an >> implementation we like. > > Good idea. Something like subdoc::path/to/doc[attributes to inherit/set just for the subdoc/not to inherit] I'm sure thats not implementable as an Asciidoc macro, it will need to be a system macro with support in the Python code. I don't know whats involved in that. Cheers Lex -- You received this message because you are subscribed to the Google Groups "asciidoc" group. To unsubscribe from this group and stop receiving emails from it, send an email to [email protected]. To post to this group, send email to [email protected]. Visit this group at http://groups.google.com/group/asciidoc. For more options, visit https://groups.google.com/d/optout.
