Getting Comments/Annotations in LyX to show up in PDF

I’ve started to use Lyx to do our technical documentation (Oh how I wish I could use Framemaker on the Mac, but Adobe destroyed the best tool for technical documentation  and made it only available on the legacy Windows virus vector. Lyx is nothing like Framemaker other than supporting structure documents. I’m just lamenting a loss of what I would be using now if I could instead of Lyx). I tried using Pages, but it does not support Structured Documents very well and has no mechanism for supporting versioning or collaboration.

I really like how Lyx is a true structured document editor. Its What You See Is What You Mean (WYSIWYM) instead of WYSIWYG. You focus on the structure and text of your document and let the tool render the document.

The main users of Lyx seem to be academics. Most of the templates are for Thesis and other academic related documents. But the Report and Article templates are fine for most technical documents and that is what I’m using.

Lyx is not for those who want to tweak the layout via GUIs (you can tweak the layout as much as you want, but you have to understand the underlying LaTeX platform and do most of  your tweaks in code). Its not a slick, ultra-friendly environment. And things get a bit confusing once you get off the beaten track of the pretty good documentation of basic stuff. It doesn’t particularly feel like a Mac App. But its the best I’ve found for doing structured technical docs in a way that is versionable (like with Git) and can support multiple people doing edits and collaboration on a document.

I’m using the 2.0 Beta which is a significant improvement over the 1.6 stable version. I’ve had no problems with the Beta and the functionality is a big improvement. You can download the Beta binary images for the Mac, Linux or if you must, Windows here: ftp://ftp.lyx.org/pub/lyx/devel/lyx-2.0/beta2.

Some things are a bit opaque as how to do. For instance, Lyx has some nice mechanisms to add Notes and Comments to the text. But these Notes and comments don’t show up in the PDF output. This is fine if you are doing all your collaboration with other folks using Lyx. But sometimes you want to share the PDF output and have the notes show up there. I could not find out a way to make Notes or Comments to  show up in the PDF. The “Greyed Out” option will show up in the PDF though.

I did discover a couple of options in the Lyx Wiki. The first one ExportWithCommentsIncluded was a bit confusing as it didn’t seem to apply to the 2.0 Beta. But if I put the code they suggest for version <1.5

\RequirePackage{colortbl, tabularx}
\@ifundefined{comment}{}% do nothing if the comment environment is not defined
  {% redefine the comment environment if it is defined
   \renewenvironment{comment}
    {% replaces \begin{comment}
     \par\medskip\noindent
     \tabularx{\textwidth}{|>{\columncolor[gray]{0.9}}X|}
     \hline
     \emph{\textbf{Comment:}}% You can use any other text instead of "Comment:" or leave it
    }
    {% replaces \end{comment}
     \endtabularx\hrule\par\medskip
    }
  }%

into the Document Preamble, (accessed via Menu Bar Document->Settings…->LaTeX Preamble), then the Comments would show up in the PDF. (Notes still does not).

Another place in the Lyx Wiki, Producing annotations and comments,  mentions you can load a module that directly uses PDF annotations. But it was a bit short on instructions on how exactly to do that. I eventually figured it out. These instructions are for Lyx 2.0 Beta 2 on Mac OS X Snow Leopard.

Save the file from the link uploads:/Modules/pdfcomment.module to ~/Library/Application Support/Lyx-2.0/layouts/pdfcomment.module. Download the file pdfcomment_v2.1.zip, unzip it and copy the file pdfcomment.sty from the unzipped directory to /Application/LyX.app/Contents/Resources/tex/pdfcomment.sty

Then inside of Lyx mouse to Menu Bar Lyx->Reconfigure. Quit Lyx and restart.

Next mouse to Menu Bar Document->Settings…->Modules, select PDF comments in the Available and click Add, then Apply (and maybe Save as Document Defaults so it will apply to all documents from then on)

Now you will have new options in Menu Bar Insert->Custom Insets: PDF-Annotation and PDF-Margin. I couldn’t see a difference between them off hand. They put the PDF annotation Icon at the point of insert and the comments you type for that tag show up in the margin of the PDF document.

You potentially can tweak the look of the PDF annotations but you need to dive into the code.

I’ll try to blog about other experiences and tips I find on Lyx as I go.