Computer Code Caption

English
, ,
#1

It’s pretty common for publications with computer code to put a numbered caption above them. Captions are supported as standard in Writer for objects like tables and images. What would be the best way of adding similar captions to computer code?

There is a side issue affecting functionality. I’ve noticed some formats affect the characters captured with a copy/past from a pdf, an important characteristic of computer code. That’s a consideration but not the topic of this post.

#2

Frame + Special Paragraph style??

#4

Using a frame does allow for a caption to be used. However, there is no caption category for a code listing. It would require modification to LibreOffice to include a caption category for code listing. This would make it very easy to insert a caption if a frame is used and allow the caption to be numbered easily. The method suggested by ajlittoz does work but is complicated to use and some LibreOffice users may not be able to cope with this.

I have tried using a frame to insert a code example, but DO NOT recommend using a frame. The biggest problem is that a frame cannot break across pages. Much better to enter a code example as normal text using the Code paragraph style. This will allow a code example to break across pages.

My recommendation would be to create a paragraph style called Code Listing positioned above the code example. This would be in Libreartion Mono font to match the code. Size to be 11 point using Italic Bold as emphasis and left aligned. The options “Do not split paragraph” and “Keep with next paragraph” would be set so that the heading remains with the first line of code.

The heading would look like this — Code Listing: Example of code lines. Using automatic numbering would not be used. The words “Code Listing:” would have to be manually entered each time and then followed by the title. Cross referencing would be easy as this system already exists in LibreOffice. The option to use when inserting a cross reference would be “Reference text”. This method is already used in the LO user guides when referring to headings includes a page number cross reference.

I have suggested using Code Listing as the style name so that it is not confused with the List paragraph styles that are already available in LibreOffice. This would make it easier for LO users to create code examples in Writer documents.

My thoughts are looking from a user’s viewpoint, not the hard-working volunteers creating the user guides.

PeeWee

#3

Insert>Caption is only a convenience command which simulates many manual additions to your document. To know the extent of the “object” to caption, this menu command presently works only on frames or tables.

The first method would be to put your code snippet into a frame. CAUTION! This implies that your code snippet can’t straddle a page break nor extend on several pages. This is fit for relatively small code samples.

But you can do captioning yourself. This is the second method. After having designed your own caption look, record the whole caption paragraph in an AutoText item for ease of reuse.

  • If you want to number your code examples separately from figures, tables, illustrations, drawings, …
    You must create a dedicated number range.
    1. Insert>Field>Other Fields, go to Variables tab
    2. In Type, select Number range
    3. Enter a dedicated name in Name, e.g. Code
    4. Choose the preferred format (usually Arabic(1 2 3))
    5. If you want to number per chapter, choose the desired level in Numbering by Chapter
    6. Insert, then Close
    7. Erase the newly inserted field (we were only creating the number range)
  • Define a dedicated paragraph style to give a common look to all your captions
    1. Display the side style pane if not already visible ( F11 except under MacOS where you must Styles>Manage Styles)
    2. Right-click on Caption and New
      You then create a style inheriting from Caption so that changes in Caption are also forwarded to all its descendants Drawing*, Figure, Illustration, Table, Text and the newly created one.
      Give a name to the style, e.g. Code.
      Unless you already have an idea on how different from Caption this style is, leave it as a duplicate for Caption. You can modify Caption for center alignment and all captions (figure, table, … and code) will be centered.

When you want to insert a caption followed by a code sample:

  1. Set the current paragraph style to Code
  2. Type "Code example " (note the space after “example”)
  3. Insert>Field>Other Fields, Variables tab, select the *Code number range
  4. Insert, then Close (unless your screen is wide enough to keep this dialog open for future code number insertion)
  5. Type ": " followed by the specific caption

Once you have one caption, select the caption up to the colon (don’t include the specific caption) and create an AutoText entry, giving it a shortcut (I used CC for “code caption”).

Next time you need a caption, type Enter cc F3. Continue by typing the specific caption.

Customisations

Your caption may be above or below the code sample. You seem to have a preference for “above”. In this case to avoid the risk of having the caption alone at the bottom of the page, tick Keep with next paragraph in Text Flow tab of either Caption (for all captions) or Code (only for code examples) paragraph styles.

This will work only if you don’t use empty paragraphs to space caption and code example. The vertical space should be defined in Indents & Spacing tab of either Caption or Code paragraph styles.

Table of code examples

Since you have a dedicated number range for your code examples/snippets, you can create a table of these at end of your book.

  1. Insert>TOC & Index>TOC, Index or Bibliography
  2. Select Table of Figures from Type
  3. Change the Title
  4. In Create from
    • tick Captions
    • select Code from Category
    • keep References in Display
5 Likes
#6

Thanks for the detail in @PeeWee post marked as the solution to ensure users are directed there.

#5

deleted
I hadn’t read the above answer, obviously.

Impressum (Legal Info) | Datenschutzerklärung (Privacy Policy)   Content on this site is licensed under a Creative Commons Attribution Share Alike 3.0 license.