Genii Weblog

Rich Text 101 - Paragraphs (updated)

Tue 19 Aug 2003, 12:04 AM



by Ben Langhinrichs
Rich Text 101 logo
Paragraphs are essential to rich text, both on forms and in rich text fields, but they are not well understood.  Even in the properties box, it is not very clear which properties are text properties and which are paragraph properties, since the title says "Text".  The easy way to remember is that the first tab is the only one that is not paragraph related.
Text properties box 1

While I plan another article on text attributes and such, it is important to take a quick look at the text properties here.  These properties, including the language tagging, are not on a paragraph basis, so they apply to either the selected text, even if it is just a single word, or to the current position, so that text typed after setting the attributes will share those attributes.  This is different than paragraph attributes, which apply to the entire paragraph even if only a single word is highlighted or a cursor is positioned.


In order to explain some of the properties shown, and a few which are not, I will show each of the tabs from the properties box and explain a bit what the options are.  Note that while there is only one properties tab for text attributes, there are five which relate to paragraphs.

Text properties box 2
Alignment - Left, right, centered, full justification or no justification.  Nothing tricky there.

First line - This is actually a combination of the first line left margin and left margin, setting an indent, outdent or no indent/outdent.  It provides a rough guide, but better precision is available by using the ruler, since the margin settings (next tab) do not allow direct setting of the first line left margin.

List - Allows the list attributes to be set, including a choice of bullets, numbers, squares, etc.  New choices include roman numerals in upper or lower case.  Tip: nested lists can be created, so that the upper level numbers continue after a lower list is created, so long as the inner list paragraphs have left margins which are indented even a tiny bit from the outer list paragraphs.  Several levels of listing are possible.

Spacing - Allows setting additional spacing of Single (default), 1.5 and Double.  Tip: you should normally use 1.5 where double spacing is called for.  It looks better and gives adequate space.

Text properties box 3
Margins - As mentioned above, only allows setting Left and Right margins, not the first line left margin, which is controlled slightly on the tab before, or a bit better using the ruler.  Tip: even though you might choose Relative margins, the absolute margins are stored as well and used in unusual circumstances, so sometimes you need to switch back and forth and set both.

Tab stops - Tabs set through the properties have been broken since R5.0, so it is very unstable to use the Evenly spaced choice instead of individually set.  Besides the L (left), R (right), and C (center) choices shown in the example, you can also use D for decimal tabs, which will force tabbed values to line up on the decimal point, if there is one.  This is nicer that either left or right justifying columns of numbers.

Pagination - These flags, and others which are not shown, control  great deal about the paragraph, but should usually not be tampered with.  Inside a table, the latter two will always be set, and are unchangeable.  The page break should usually be added by inserting a page break, instead of by checking this flag.  Generally, leave these alone.

Text properties box 4
New in ND6

Sets a border like that of a table around the paragraph.  This mimics the CSS settings which allow a border to be placed around a block of text.  The same special effects available on a table cell, including border thickness and color and drop shadow, are available for a paragraph.  This is a very handy way of setting stuff apart without creating and removing tables.

Text properties box 5
Hide paragraph from - These are convenient for setting global settings to hide from the client, browser or mobile clients such as smart telephones.  The Mobile flag is only available in ND6 and above.

Hide paragraph when document is - These have been around since early days in Lotus Notes, except the new (in ND6) Embedded, which hides the paragraph when this is shown in an embedded editor (see Rocky Oliver's post about embedded editors).

Hide paragraph if formula is true - Hide when formula for paragraph.  Extremely powerful, but buggy, feature which lets you determine by a formula whether the paragraph is hidden.  The formula should not normally be an @If test, but just a simple formula which evaluates to True or False, such as Row != 15.  It is often a good idea to add a clause allowing visibility when the document is in edit mode, so that the text can be accessed when the formula is otherwise always True (e.g., Row != 15 & !@IsDocBeingEdited).

Text properties box 6
Paragraph styles - These allow paragraph styles to be stored with a name, including text attributes (called "font") if so desired.  This can be very handy for setting up specific looks for various parts of a rich text field, such as the headers, but these are not anywhere as reliable or robust as styles in Word or WordPro.


Part of the confusion about paragraphs in rich text stems from a fundamental architectural design choice in Lotus Notes/Domino.  Forms are made up of rich text themselves, including paragraphs, so paragraphs in rich text fields may reflect paragraph settings from the form or embedded within the paragraph itself.  This explains a very odd recommendation you may see on the public forums regarding hide-when formulas.

The issue is that if a form contains a hide-when formula which includes the rich text field, and documents are created using that form, the hide-when formula is embedded inside the rich text itself.  If the form is changed to remove or change the hide-when formula, the old hide-when formula takes precedence.  The recommendation is therefore to add a single space before the rich text field, which often has the effect of forcing the new hide-when formula onto the contents of the rich text field.  This works often enough to be useful, but all that is really happening is that the paragraph is started with the new hide-when formula, so the initial text in the rich text field uses that new formula.  Unfortunately, if there are additional paragraphs which change any paragraph settings at all, such as margins, list type. tabs or whatever, the old hide-when formulas will take effect, so this recommendation is of limited use.

I may add additional information to this article at a later point.  This is all as of Aug. 18, 2003.

Continued on Aug. 20, 2003 because a thread in the Gold forum reminded me of some information that would be valuable to clarify.

How do I tell when a paragraph starts and ends?
This is not as simple as you might think.  A common misconception is that a paragraph ends when a return (also known as a "line break" or "newline") is found.  In fact, there are two different kinds of returns.  The first is a "hard return", which is what you get when you press the Enter key in a rich text field in Notes.  A hard return does end the previous paragraph and start a new paragraph.  There is also a "soft return", which is just a newline or CRLF and can be added to rich text by holding down the Shift key while pressing Enter.  The difference can be seen in the following example.  Each bullet item is a new paragraph, but there is a soft return on the second item which does not start a new paragraph and so does not get a bullet.

  • Item 1
  • Item 2
    continuation of Item 2
  • Item 3

This still doesn't fully answer how we know when a paragraph starts and stops.  Here are a few tips.  

  1. There is always a paragraph, so the first paragraph starts at the beginning of the field.
  2. Every table cell starts with a new paragraph, and there is a new paragraph after every table.
  3. Every section starts with a new paragraph, and there is a new paragraph after every section.
  4. Every layer starts with a new paragraph, but there is not necessarily a new paragraph after every layer, since a layer anchor is actually in-line.
  5. A horizontal rule 
    does NOT start a new paragraph, although it often looks like it does when it is added (because it defaults to 100% width).
  6. In any list, such as a bullet list of numbered list, if it looks like a new paragraph, but there is no new list indicator, and the list continues afterwards, it is probably just a pseudo-paragraph using soft returns.

    This is an example of what I mean.  This is not a new paragraph.
  7. If the current properties have either a regular indent on the first line, or a hanging indent (aka, an "outdent"), and something looks like a new paragraph but does not indent/outdent, it is probably not a real paragraph.

What does the error about "Paragraph or field cannot be larger than 64k bytes." mean?
This error simply indicates that a paragraph is limited in size, due to an internal storage methodology in Notes.  The 64K is hard to measure because of hidden text, multi-byte characters (it is not 64k characters, but 64k bytes), and internal records such as graphics and buttons and such.  This is an error to try and avoid, since it can be hard to fix after the fact.  In particular, watch for multiple text fields in a single paragraph, watch for fields populated by an @DbLookup and watch for fields that might expand, such as name fields that are stored canonicalized even though they are entered in simpler form.

A good thing to remember is that each table cell starts a new paragraph, so using a table, even a table which is not visible, allows you to add multiple fields on the same line without running into this limitation.

Again, this article is likely to be continued as new questions come up.  This is all as of Aug. 20, 2003.

Copyright © 2003 Genii Software Ltd.

What has been said:


38.1. Tom Duff
(08/20/2003 12:38 PM)

Good info, Ben... Thanks for sharing.


38.2. Ben Langhinrichs
(08/20/2003 09:29 PM)

Thanks! I'm not always sure to whom I am addressing these articles. They are almost mind dumps since there is not a lot of information on rich text out there and I don't always know what people do and do not know.


38.3. Ian
(08/21/2003 08:52 AM)

Thanks for sharing this, look forward to more.


38.4. Henry Kaye
(09/22/2003 07:09 AM)

Excellent!

Maybe in a future add-on, you can deal with a common problem where a rich text field contains only string of text, lacking the LF/CR delimiter.


38.5. Kai Alingalan
(07/21/2004 12:25 AM)

Very Helpful, thanks a lot for sharing.


38.6. Big Bazza
(27/07/2004 11:00 PM)

Cheers Benjamin, very illuminating.


38.7. Joe Mainusch
(26.09.2004 03:42)

Ben,

your saved my life with the hint to the blank before the rt-field. I had a hide-when formula for rt-fields, and this formula had to be changed. None of the rt-fields couldn't be seen anymore.

With your advise I got out of hell...

Thank you.

Joe


38.8. Ossi
(30.01.2005 18.21)

I'm getting these strange "Paragraph or field cannot be larger than 64k bytes." errors when receiving some (not all) e-mails to our Notes 5. Perhaps our database administrator has misconfigured something? Any ideas of workarounds?


38.9. Subhendu Moahnty
(04/13/2005 12:39 PM)

Good info, Ben.... It help me a lot as I was suffring from the Hide formulas of RichText Field.

Great. Keep Informing.

Subhendu