On 05/12/11 18:56, Lex Trotman wrote:
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 :)
Ok, I did not know that.
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.
I think you're probably right Lex. I just wonder if using the existing comment
block syntax might add a bit of consistency e.g.
[annotation,dag,2011-12-03]
/////////////////////////////////////////////////////////
FIXME: Insert the various features from the Release Notes
include the information from the presentations
/////////////////////////////////////////////////////////
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 :)
Yes it has.
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.
