PDF-comment.lyx: finish description

- describe PDF-square and PDF-reply
- tune some minor other things

lib/examples/PDF-comment.lyx

@@ -4,9 +4,20 @@
 \begin_header
 \textclass scrartcl
 \begin_preamble
+% to be able to use all color settings of pdfcomment
 \usepackage[svgnames,rgb]{xcolor}
+
+% if pdflatex is used
+\usepackage{ifpdf}
+\ifpdf
+
+% set fonts for nicer pdf view
+\IfFileExists{lmodern.sty}
+ {\usepackage{lmodern}}{}
+
+\fi % end if pdflatex is used
 \end_preamble
-\options index=totoc,BCOR7.5mm,captions=tableheading
+\options index=totoc,BCOR7.5mm,captions=tableheading,pagesize
 \use_default_options false
 \begin_modules
 pdfcomment
@@ -385,8 +396,8 @@ status open
 status collapsed
 
 \begin_layout Plain Layout
-color=blue,height=2.5cm,width=5.8cm,voffset=-2.8cm,hoffset=8cm,opacity=1.0,justifica
+id=1,color=blue,height=2.5cm,width=5.8cm,voffset=-2.8cm,hoffset=8cm,opacity=1.0,just
-tion=right,icolor=
+ification=right,icolor=
 \begin_inset ERT
 status collapsed
 
@@ -543,6 +554,7 @@ As you can see a PDF-Line comment without options is useless.
 \begin_layout Standard
 The green arrow at the left side of this page is an example for a PDF-Line
  comment with options.
+ 
 \begin_inset Flex PDF-Line
 status open
 
@@ -657,7 +669,7 @@ status open
 
 \begin_layout Plain Layout
 \begin_inset Argument 1
-status open
+status collapsed
 
 \begin_layout Plain Layout
 icon=Note,color=red,open=true,hspace=100pt
@@ -678,11 +690,14 @@ PDF-Markup
 \end_layout
 
 \begin_layout Standard
+This will typeset so called PDF text markup annotations over some text or
+ math.
+ Here is a markup without options: 
 \begin_inset Flex PDF-Markup
 status open
 
 \begin_layout Plain Layout
-PDF-Markup
+simple PDF-Markup
 \end_layout
 
 \end_inset
@@ -690,16 +705,247 @@ PDF-Markup
 
 \end_layout
 
+\begin_layout Standard
+Possible types for the option 
+\series bold
+markup
+\series default
+ are:
+\end_layout
+
+\begin_layout Description
+Highlight The markup text will be highlighted: 
+\begin_inset Flex PDF-Markup
+status open
+
+\begin_layout Plain Layout
+\begin_inset Argument 1
+status open
+
+\begin_layout Plain Layout
+id=1,markup=Highlight
+\end_layout
+
+\end_inset
+
+Highlight PDF-Markup
+\begin_inset Argument post:1
+status open
+
+\begin_layout Plain Layout
+a comment
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\end_inset
+
+
+\begin_inset Note Note
+status collapsed
+
+\begin_layout Plain Layout
+see the next section for the description of the option 
+\series bold
+id=1
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Description
+Underline The markup text will be underlined: 
+\begin_inset Flex PDF-Markup
+status open
+
+\begin_layout Plain Layout
+\begin_inset Argument 1
+status open
+
+\begin_layout Plain Layout
+markup=Underline
+\end_layout
+
+\end_inset
+
+Underlining PDF-Markup
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Description
+Squiggly The markup text will be underlined with a wave: 
+\begin_inset Flex PDF-Markup
+status open
+
+\begin_layout Plain Layout
+\begin_inset Argument 1
+status open
+
+\begin_layout Plain Layout
+markup=Squiggly
+\end_layout
+
+\end_inset
+
+Underwave PDF-Markup
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Description
+StrikeOut The markup text will be striked-out: 
+\begin_inset Flex PDF-Markup
+status open
+
+\begin_layout Plain Layout
+\begin_inset Argument 1
+status open
+
+\begin_layout Plain Layout
+markup=StrikeOut
+\end_layout
+
+\end_inset
+
+Striked-out PDF-Markup
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Standard
+The text for the comment is inserted with the inset option 
+\family sans
+Comment
+\family default
+.
+\end_layout
+
+\begin_layout Standard
+PDF-Markup has some limitations:
+\end_layout
+
+\begin_layout Itemize
+it is only suitable for text or inline math!
+\end_layout
+
+\begin_layout Itemize
+the markup text must not be longer than one paragraph
+\end_layout
+
+\begin_layout Itemize
+the markup annotation must not be longer than one page, otherwise the recognitio
+n of the page break will fail
+\end_layout
+
+\begin_layout Itemize
+when using XeTeX you have to assure that the page dimensions are internally
+ output, e.
+\begin_inset space \thinspace{}
+\end_inset
+
+g.
+\begin_inset space \space{}
+\end_inset
+
+with the document class option 
+\series bold
+pagesize
+\series default
+ for the KOMA-Script classes, or the option 
+\series bold
+pagesize
+\series default
+ for the LaTeX-package 
+\series bold
+typearea
+\series default
+.
+\end_layout
+
 \begin_layout Subsection
 PDF-Reply
 \end_layout
 
 \begin_layout Standard
+With a PDF-Reply you can compose replies to PDF-comments.
+ The option 
+\series bold
+replyto
+\series default
+ provides a clear reference to the comment the reply refers to.
+\end_layout
+
+\begin_layout Standard
+As example see the reply to the Highlight PDF-Markup from the previous section.
+ 
 \begin_inset Flex PDF-Reply
 status open
 
 \begin_layout Plain Layout
-PDF-Reply
+\begin_inset Argument 1
+status open
+
+\begin_layout Plain Layout
+id=2,replyto=1,date=D:20101211161247+01'00'
+\end_layout
+
+\end_inset
+
+This is a reply.
+\end_layout
+
+\end_inset
+
+ It appears in that PDF-Markup comment.
+ To be able to reference the PDF-Markup the option 
+\series bold
+id=1
+\series default
+ was added to its options.
+ The PDF-Reply got the option 
+\series bold
+replyto=1
+\series default
+.
+\end_layout
+
+\begin_layout Standard
+You can also reply to replies by adding an 
+\series bold
+id
+\series default
+ option to the reply that should be replied to.
+ As example see the reply to the reply to the PDF-Markup.
+ 
+\begin_inset Flex PDF-Reply
+status open
+
+\begin_layout Plain Layout
+\begin_inset Argument 1
+status open
+
+\begin_layout Plain Layout
+replyto=2,date=D:20101212095321+01'00'
+\end_layout
+
+\end_inset
+
+Of course, you can reply to a reply.
 \end_layout
 
 \end_inset
@@ -707,16 +953,154 @@ PDF-Reply
 
 \end_layout
 
+\begin_layout Standard
+\begin_inset Note Greyedout
+status open
+
+\begin_layout Plain Layout
+
+\series bold
+Note:
+\series default
+ Due to technical reasons PDF-Reply works only while using pdflatex.
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Standard
+PDF-Reply has some further limitations:
+\end_layout
+
+\begin_layout Itemize
+It can not support page breaks.
+\end_layout
+
+\begin_layout Itemize
+The replies will only appear in the PDF annotations on the second page.
+ (Replies to comments without page break work smoothly.)
+\end_layout
+
 \begin_layout Subsection
 PDF-Sideline
 \end_layout
 
+\begin_layout Standard
+This will typeset a comment in form of identical markers on every side of
+ the page.
+ The yellow arrows besides this text is an example without any options:
+ 
+\begin_inset Flex PDF-Sideline
+status open
+
+\begin_layout Plain Layout
+a simple PDF-Sideline
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Standard
+As you can see a PDF-Sideline comment without options is quite useless.
+ PDF-Sideline is useful if you want to highlight complete parts of a page.
+ The inset options define the layout of the marker while the normal content
+ of the inset is the text surrounded by the markers.
+ The content of the inset option 
+\family sans
+Comment
+\family default
+ will be printed along both markers.
+ Here is an example:
+\end_layout
+
 \begin_layout Standard
 \begin_inset Flex PDF-Sideline
 status open
 
 \begin_layout Plain Layout
-PDF-Sideline
+\begin_inset Argument 1
+status open
+
+\begin_layout Plain Layout
+opacity=0.33,color=magenta,icolor=cyan,caption=inline,linebegin=
+\begin_inset ERT
+status collapsed
+
+\begin_layout Plain Layout
+
+{
+\end_layout
+
+\end_inset
+
+/Butt
+\begin_inset ERT
+status collapsed
+
+\begin_layout Plain Layout
+
+}
+\end_layout
+
+\end_inset
+
+,lineend=
+\begin_inset ERT
+status collapsed
+
+\begin_layout Plain Layout
+
+{
+\end_layout
+
+\end_inset
+
+/Square
+\begin_inset ERT
+status collapsed
+
+\begin_layout Plain Layout
+
+}
+\end_layout
+
+\end_inset
+
+,linewidth=3bp,linesep=0.7cm
+\end_layout
+
+\end_inset
+
+Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy
+ eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam
+ voluptua.
+ At vero eos et accusam et justo duo dolores et ea rebum.
+ Stet clita kasd gubergren, no sea takimata sanctus est Lorem ipsum dolor
+ sit amet.
+ Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy
+ eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam
+ voluptua.
+\end_layout
+
+\begin_layout Plain Layout
+At vero eos et accusam et justo duo dolores et ea rebum.
+ Stet clita kasd gubergren, no sea takimata sanctus est Lorem ipsum dolor
+ sit amet.
+ Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy
+ eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam
+ voluptua.
+ At vero eos et accusam et justo duo dolores et ea rebum.
+ Stet clita kasd gubergren, no sea takimata sanctus est Lorem ipsum dolor
+ sit amet.
+\begin_inset Argument 2
+status open
+
+\begin_layout Plain Layout
+Comment text
 \end_layout
 
 \end_inset
@@ -724,20 +1108,105 @@ PDF-Sideline
 
 \end_layout
 
+\end_inset
+
+
+\end_layout
+
+\begin_layout Standard
+PDF-Sideline has some limitations:
+\end_layout
+
+\begin_layout Itemize
+the markup annotation should not be longer than one page, otherwise the
+ recognition of the page could fail
+\end_layout
+
+\begin_layout Itemize
+when using XeTeX you have to assure that the page dimensions are internally
+ output, e.
+\begin_inset space \thinspace{}
+\end_inset
+
+g.
+\begin_inset space \space{}
+\end_inset
+
+with the document class option 
+\series bold
+pagesize
+\series default
+ for the KOMA-Script classes, or the option 
+\series bold
+pagesize
+\series default
+ for the LaTeX-package 
+\series bold
+typearea
+\series default
+.
+\end_layout
+
 \begin_layout Subsection
 PDF-Square
 \end_layout
 
+\begin_layout Standard
+This will typeset a rectangular box.
+ Here is an example without any options: 
+\begin_inset Flex PDF-Square
+status open
+
+\begin_layout Plain Layout
+a simple PDF-Square comment
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Standard
+Below this text you see a rectangle comment with a curvy outline as example
+ of a PDF-Square with options.
+\end_layout
+
 \begin_layout Standard
 \begin_inset Flex PDF-Square
 status open
 
 \begin_layout Plain Layout
-PDF-Square
+\begin_inset Argument 1
+status collapsed
+
+\begin_layout Plain Layout
+height=2cm,width=4.8cm,voffset=-2cm,hoffset=1cm,opacity=1.0,justification=right,ic
+olor=CornflowerBlue,bse=cloudy,bsei=2.5,linewidth=8pt
 \end_layout
 
 \end_inset
 
+A fancy PDF-Square comment
+\end_layout
+
+\end_inset
+
+
+\begin_inset Newline newline
+\end_inset
+
+
+\begin_inset Newline newline
+\end_inset
+
+
+\begin_inset Newline newline
+\end_inset
+
+
+\begin_inset Newline newline
+\end_inset
+
 
 \end_layout
 
@@ -746,7 +1215,7 @@ PDF-Tooltip
 \end_layout
 
 \begin_layout Standard
-With this you can annotate any object with a tooltip
+With this you can annotate any object with a tooltip.
 \begin_inset Foot
 status open
 
@@ -960,6 +1429,18 @@ PDF-Markup in orange
 \end_inset
 
 
+\begin_inset space ~
+\end_inset
+
+
+\begin_inset space ~
+\end_inset
+
+
+\begin_inset space ~
+\end_inset
+
+
 \begin_inset Flex PDF-Annotation
 status collapsed
 
@@ -1001,9 +1482,9 @@ PDF-Comment style
 This environment allows you to define a style for a PDF-comment that can
  be used by several comments.
  Assuming you write a Math tutorial and want to add popup explanations in
- the PDF for several expressions, then insert a PDF-Comment style einvironment
+ the PDF for several expressions, then insert a PDF-Comment style environment
- before your fiirst formula.
+ before your first formula.
- Name it 
+ Name it for example 
 \series bold
 MathPopup
 \series default
@@ -1011,11 +1492,11 @@ MathPopup
 \series bold
 color=white
 \series default
- and make the comment popup with 
+ and highlight the whole formula with 
 \series bold
 markup=Highlight
 \series default
- (will pop up when the mouse is hovered over the formula).
+.
 \end_layout
 
 \begin_layout Define PDF-Comment Style
@@ -1333,7 +1814,8 @@ You can insert a list with all PDF-comments using the environment List of
  PDF-comments.
  By specifying options for it you can determine what parts of the comments
  shpuld appear in the list.
- Here is the list for this document:
+ Here is the list for this document where only the comments of a defined
+ author are printed:
 \end_layout
 
 \begin_layout List of PDF-Comments
@@ -1349,21 +1831,109 @@ liststyle={AuthorComment}, heading ={List of PDF-comments}
 
 \end_layout
 
-\begin_layout Section
+\begin_layout Standard
-General Hints
+You can also define your own style using the environment
+\begin_inset Newline newline
+\end_inset
+
+
+\family sans
+Define
+\begin_inset space ~
+\end_inset
+
+PDF-Comment
+\begin_inset space ~
+\end_inset
+
+List
+\begin_inset space ~
+\end_inset
+
+Style
+\begin_inset Newline newline
+\end_inset
+
+
+\family default
+if you know enough about the tricky LaTeX internals.
+ With the environment
+\begin_inset Newline newline
+\end_inset
+
+
+\family sans
+Set
+\begin_inset space ~
+\end_inset
+
+PDF-Comment
+\begin_inset space ~
+\end_inset
+
+List
+\begin_inset space ~
+\end_inset
+
+Style
+\begin_inset Newline newline
+\end_inset
+
+
+\family default
+you can set a list style in case it was changed before the list of comments.
 \end_layout
 
-\begin_layout Define Avatar
+\begin_layout Define PDF-Comment List Style
 \begin_inset Argument 1
 status open
 
 \begin_layout Plain Layout
-Cyrillic
+MyStyle
 \end_layout
 
 \end_inset
 
-color=Green,open=true,icon=Key,author={a}
+
+\backslash
+makeatletter
+\backslash
+pc@lopt@author
+\backslash
+ - 
+\backslash
+pc@lopt@subject
+\backslash
+ (
+\backslash
+pc@lopt@deadline)
+\backslash
+makeatother
+\end_layout
+
+\begin_layout Set PDF-Comment List Style
+AuthorCommentDeadline
+\end_layout
+
+\begin_layout Standard
+\begin_inset Note Greyedout
+status open
+
+\begin_layout Plain Layout
+
+\series bold
+Note:
+\series default
+ Only one list of comments can be printed in the PDF.
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Section
+General Hints
 \end_layout
 
 \begin_layout Itemize
@@ -1471,31 +2041,9 @@ Oleg also said: I hate to repeat myself.
 \end_layout
 
 \begin_layout Itemize
-It you have non-Latin characters in your comment or in the author name ...
+You cannot use non-Latin characters in your comment or in the author name.
-\end_layout
+ The reason is that PDFs use a special character encoding that is not compatible
-
+ with LaTeX.
-\begin_layout Standard
-Here is an example of a comment containing non-Latin characters:
-\begin_inset Flex PDF-Margin
-status open
-
-\begin_layout Plain Layout
-\begin_inset Argument 1
-status open
-
-\begin_layout Plain Layout
-avatar=Cyrillic
-\end_layout
-
-\end_inset
-
-Here is a text with Cyrillic letters: Александр Исаевич Солженицын got the
- nobel price in 1970.
-\end_layout
-
-\end_inset
-
-
 \end_layout
 
 \end_body