On Mon, Dec 5, 2011 at 3:47 PM, Stuart Rackham <[email protected]> wrote: > > > On 05/12/11 14:10, Dag Wieers wrote: >> >> On Mon, 5 Dec 2011, Lex Trotman wrote: >> >>> I have to disagree about this, comment blocks are meant to not >>> generate output, we should not change that in a backward incompatible >>> way. Using the same markup in different ways in different backends is >>> a "bad thing" (tm). >> >> >> I wasn't talking about comment blocks, but commented lines. > > > Comments have two common functions: for temporarily excluding content and > for notes that are *not* intended to be read buy the document consumer. > > An annotation on the other hand is meant to be read by the document > consumer. > > lowriter uses an 'Insert->Comment' command to insert an office:annotation > element which is readable if you open the document with lowriter, but it is > not readable from a printed version of the document. Kind of confusing, but > I guess the rationale is that odf source documents are for document > creators, printed outputs are for consumers -- in this respect they are > comments not annotations.
Actually they are optional annotations since you can set print options to show them in printed output as well :) > > Here's my question: if you are are authoring a document using asciidoc (i.e. > not lowriter) what is the point of passing comments through to ODF? I think there is a good use-case for comment type content that is optionally visible in the output (eg "this multi-line list of things need to be done before release") and content that is never visible in the output (eg commenting out sections that don't apply yet). Since this is "out-of-band" content, if it is visible it should be visually distinct from normal annotations (at least it should allow it to be styled as such) and so using standard annotations isn't appropriate. In standard asciidoc, comment blocks are never visible, whilst the comment lines are optionally visible. So all that is missing is an optional multiline entity. I don't see a problem with this being in the form of another annotation with a "comment" style generating <remark role="comment-annotation"> for docbook, <office:annotation> for ODT and <p class="comment-annotation"> for HTML if :showcomments: is set. Having a separate entity like this makes it backward compatible with existing block comments and line comment behaviour. Sadly as I said last time I can't think of a better name than "comment annotation" since the percieved use is for optional visible annotations or comments on the text :). But this may be confusing (indeed I think that has already happened :) Then everyone is happy(ish). Cheers Lex > > Cheers, Stuart > > >> >> >>> However adding a new block output type as Stuart suggested should be >>> ok. But the terminology needs to be clear. It should be easy to make >>> it clear that you are talking about a comment block which doesn't >>> produce output or comment xxx that does. >> >> >> That's why I called it an annotation block. >> >> >>> It looks to me to be another form of annotation with author and date >>> options. So long as you can suggest backends for html and docbook >>> that generate the same look as ODT then it should be ok to be added to >>> standard asciidoc. A comment annotation should be sufficiently >>> different from a comment block to be easy to distinguish. >> >> >> But for working with AsciiDoc files, comments are a lot more convenient >> than >> annotation blocks as proposed by Stuart IMNSHO. >> >> However I did implement it now, updated the README and added examples to >> the >> test-odt.txt. Annotations are also described in the DocBook syntax. >> > > -- > You received this message because you are subscribed to the Google Groups > "asciidoc" group. > To post to this group, send email to [email protected]. > To unsubscribe from this group, send email to > [email protected]. > For more options, visit this group at > http://groups.google.com/group/asciidoc?hl=en. > -- You received this message because you are subscribed to the Google Groups "asciidoc" group. To post to this group, send email to [email protected]. To unsubscribe from this group, send email to [email protected]. For more options, visit this group at http://groups.google.com/group/asciidoc?hl=en.
