Text Formatting ⇒ Square brackets for comments

[g0mug0mu]

Hi,

I was hoping someone could give me some advice on what convention they use in latex to denote text which would require revision at some point in the future, or which generally should be double-checked before document completion. I am familiar with the convention of surrounding incomplete or draft text with square brackets. For example:

The earth is [3,000] years old.
or
In the event that a fire alarm sounds in the building

to the nearest fire escape. Where in both cases, the author may believe that the word should be revised and that additional research may be required before the sentence can be finalised. While I would be more than happy to use square brackets, I have had some instances with latex not compiling properly as a result of my usage of square brackets for denote draft text. In general, I suppose I am after a safe symbol which is not reserved in any way by latex. Many thanks in advance for your help.

[frabjous]

Typically I use comments starting with % in the code as notes to myself. As you probably know, LaTeX suppresses a % and everything after it from affecting the output. I don't see why I need it to show in the output as well.

But if you do want it to be visible in the output: does it have to be a symbol? If nothing else, a symbol will change the dimensions of what I'm typesetting, possibly leading to a need to rearrange after removing the flag. I'd probably use a color instead, e.g., put sections I want to flag in blue or something like that.

[g0mug0mu]

You make a good point regarding the formatting impact of the symbol frabjous. The rationale behind using a symbol (which is preferably unused throughout the rest of the document) is that it allows for an effective way to find and replace at a later date when checking through a lengthy document where the author may fail to remember where further edits are required. The commenting option is good when one does not wish to put in draft wording but when you are like me, you liken your writing process to an initial verbal projectile vomit onto the page followed by a cleaning process that occurs at a later date. I like the idea of text colouring, especially since this would make required edits quite obvious on inspection of the output document (although not necessarily so well if printed in black and white). My issue with text coloring is the length of the syntax required every time i wish to make something 'markup style', as well as the additional potential of syntax error.

So i suppose, in addition to my first post, the 'markup' symbol would preferably:

• - Require minimal syntax
  - Be conspicuous in a black and white printout
  - Be otherwise unused throughout the rest of the document (as much as possible) to facilitate the process of searching for said symbols
  - Not suppress output of the markup text

Any thoughts?

[johnjamessmith0]

Any repeated use of clunky syntax can and should be reduced by defining your own commands. This is in fact generally easy to do, so it should not be problem. As for searching for symbols, it seems to me that one would want to have the special symbol most searchable in the .tex file rather than in the output necessarily, since that's where you're going to be making the changes directly. How would a solution that is not directly searchable in, say, a pdf but conspicuous in appearance nonetheless, while still being searchable in the LaTeX code (e.g., putting a box around the text, underlining, changing the typeface, making it bold, making the text white and the background black, etc.)?

(So changing the color satisfies three of your four criteria rather nicely, with the additional benefit described by frabjous. But if you insist it being in black-and-white...)

Beyond that, I would think your problem has little to do with LaTeX. Almost anything will work. There are plenty of funny symbols out there -- take your pick (http://www.ctan.org/tex-archive/info/sy ... ols-a4.pdf). Or if you're used to square brackets, consider making a command like

Code: Select all

\newcommand{\B}[1]{[#1]}

used as in:

Code: Select all

The earth is \B{3,000} years old.

(Is two characters extra OK?)

[g0mug0mu]

johnjamessmith0, you make a good point regarding not needing to perform the search in the output document. I particularly like the idea of putting a box around the text as this is far more obvious than a square bracket when reading over a hard copy of a draft. Custom syntax is also a good idea. I'm also just generally interested to hear what other people are using as their convention. For now, I think i will go with the box around the text...

[meho_r]

Apart from what's been already suggested, a note about the visual part in the output: I'd probably use a custom command which will mark those places that need reviewing with, let's say, red color (which will turn to grey in black-and-white print) and maybe make them bold, but I'd also add a thick rule, a cube, a circle or some other symbol/sign (or even a word) to the margin for every single line containing those parts. This way you'll make it even easier for a reviewer to spot those places (or, not to omit any of them, especially in black-and-white print), while leaving you a mean to easily find those places in the source file and do all necessary changes.

Also, be careful with boxes since they cannot be split and broken across lines and pages, so if you have to mark a complete sentence which occupy two or more lines, things can get messy.

An additional note: line numbers also may be very useful in reviewing process, especially when you have to discuss some parts of a document which were not marked previously, since it's much easier to refer to a line number than to a page, paragraphs etc. For this purpose you may use lineno package.

[g0mug0mu]

meho_r, thanks for the great advice, esp. wrt margin marks and problems with the box, glad i don't have to find out through frustrated experience!

[localghost]

If the problem is solved now, please be so kind and mark the topic accordingly as described in section 3 of the Board Rules (to be read before posting).


Best regards and welcome to the board
Thorsten

[g0mug0mu]

Thanks thorsten, i have marked the topic as resolved, although i suppose the question was fairly open ended and I would still be happy to hear about what other conventions people are using as there may be other equally valid approaches.