LO Chapter Template 7-4

The second draft of the LO chapter template is now available in Contributor Resources on NextCloud ready for reviews and comment.
There has been a few changes thanks to the input from Flywire and Olivier.
If no-one responds in the next few days, I will presume that everybody is happy with the template.

Regards
Peter Schofield
Technical Writer, LO Documentation Team

Peter,

I’ll just make a few more comments on the code part of the template. As a non-programmer, you’ve done an excellent job with the code.

  1. very light code style background (which was removed) helped readers clearly focus between text and code as the two are cross-referenced
  2. code text size to fit 80 characters/line (10.7 pt) is more readable
  3. colored code styles should contain nothing except a color setting
  4. base colored style(s) should inherit from Code (see image)
  5. As we have discussed, the character style trees _LOCodeBase and _OOoComputerBase need to be combined into a single style tree (see image). The Code Colorizer Formatter » Extensions author should probably do this.

Note: Base character style trees _LOCodeBase and _OOcComputerBase are essentially duplicates


The following is an example of how code will look when it is inserted into a user guide chapter and the Code paragraph style has been applied.

The character styles from the original programming language are not affected when the Code paragraph style is applied. These character styles will appear in the Character Styles panel in the Styles deck on the Sidebar.

This is wrong and needs to be tweaked. Suggest (without bold):

The following is an example of how code will look when it is inserted into a user guide chapter with the Code paragraph style and syntax highlighting applied.

Delete paragraph after the code because the effects on character styles from the original code vary widely, are fairly unpredictable, and they certainly won’t have LO character styles applied.

Add:

5) Ensure the syntax highlighting extension is installed and configured.
6) Apply syntax highlighting to each snippet (segment) of code. Keyboard shortcuts are worthwhile for numerous snippets.
7) Code style will be updated, most noticeable by a change in colors, as new character styles are added to the document if they don’t exist.

Different action might be required with Point 5. about the character style tree. All editorial comments I made would stand.

Hello Flywire

  1. Light grey highlighting colour added to Code paragraph and character styles.

  2. The present setting of 10pt is fine for Code and it is still readable. Using fractions of a point for size can cause problems (that its from past experience, not LO). Picas and points are a very old measuring system for fonts and characters. They have been around for a couple of hundred years from when type was set in lead, nothing electronic.

  3. The Code Colorise Formatter extension - when applied it adds the colour to the characters, but removes the highlighting applied with the Code paragraph or character style. Makes the code lines look a little odd. Also, need to know the programming language used. Using the Automatic and Default options it is not correct. See original sample the second sample below.

Peter Schofield
psauthor@gmail.com
Technical Writer, LO Documentation Team

Original sample

sub EnterMyName

rem -------------------------------------------------------------

rem define variables

dim document as object

dim dispatcher as object

rem -------------------------------------------------------------

rem get access to the document

document = ThisComponent.CurrentController.Frame

dispatcher = createUnoService(“com.sun.star.frame.DispatchHelper”)

rem -------------------------------------------------------------

dim args1(0) as new com.sun.star.beans.PropertyValue

args1(0).Name = “Text”

args1(0).Value = “Your name”

dispatcher.executeDispatch(document, “.uno:InsertText”, “”, 0, args1())

end sub

After Code Colorise Formatter

sub EnterMyName

rem -------------------------------------------------------------

rem define variables

dim document as object

dim dispatcher as object

rem -------------------------------------------------------------

rem get access to the document

document = ThisComponent**.CurrentController.**Frame

dispatcher = createUnoService("com**.sun.star.frame.**DispatchHelper")

rem -------------------------------------------------------------

dim args1(0) as new com**.sun.star.beans.**PropertyValue

args1(0)**.**Name = “Text”

args1(0)**.**Value = “Your name”

dispatcher**.executeDispatch(document,** ".uno:InsertText", "", 0**,** args1())

end sub

I agree, you need to know the language to know which syntax to use. The original author would know that, and hopefully, there might be some improvements here.

The style issue is the styles are not linked properly, if they were the desired style must flow through. I’m confident points 3 to 5 in my previous post would resolve those issues. The difference in the samples is not clear to me.

I understand now. If the macro is overwriting the style then the style in the macro needs fixing. A macro needs to identify the syntax and the styles set the appearance.

Styles should inherit everything except the attributes that need to change. eg Code sets default font, size, color, background etc; the other styles inherit everything except color. In this example Name.Function is changed to bold but if it was moved to code it would apply to all code like the background does. Ultimately a master style sheet will overwrite all the styles in the chapter documents anyway.

Hello Flywire

I will now create Code character styles with colour using the same settings as the character styles that were imported into the template from the extensions. I will also use a similar name, but the each character style will begin with Code. Obviously, the extensions should not be used until they are fixed.

Regards

Peter Schofield
psauthor@gmail.com
Technical Writer, LO Documentation Team

I think you should just create the code styles and leave the extension to create the child styles. You can describe the colors defined in Color Config Entry.


A heads up the code style colors might need investigating, trying to load them to Pygments they failed the contrast test:

Pygments styles should be accessible to people with suboptimal vision. This test ensures that the minimum contrast of styles does not degrade, and that every rule of a new style fulfills the WCAG AA standard.

The file LO-UG-Chapter-Template-7-4.ott is now in Contributor Resources on NextCloud. In my opinion it is now ready for use, but feel free to comment and review.

The following has been changed:

  1. Contributors is now in column format using paragraph style Column Contents. Also, I have removed “To this edition” and To previous editions”. Both of the changes are to increase the space available on the Copyright page and keep the Copyright page to a single page. The list of contributors is very getting long and I think we should reduce the list to recent contributors that have been involved with recent editions.

  2. All paragraph styles, have the option “Do not split paragraph” selected. This prevents paragraphs from breaking across two pages and creates a document with good format. However, care must be taken when creating paragraphs to prevent them from being too long. Please read the instructions.

  3. Inserting, position and captioning figures has changed to improve the formatting of a user guide. Please read the instructions.

  4. Text in figures has been a problem for translators. It has now been fixed by introducing a numbered legend for figures. Figures 5 and 6 give an example of what I mean. The legend for a figure uses the the styles Definition Term and Legend Numbered. Legend Numbered was created as a separate numbered list to be used in column format matching the numbers used in the figure. Instructions are provided.

  5. A section on inserting code examples into a document has been included. Code paragraph and character styles are used. Having never inserted code examples similar to those used in LO user guides, I may have got it wrong and the instructions may have to be changed.

  6. There has been a general improvement in instructions to make them clearer and easier to understand. Hopefully, this will make the template easier to use.

Enjoy.

With regards
Peter Schofield
psauthor@gmail.com
Technical Writer, LO Documentation Team

CodeHighlighter2 has some cosmetic changes which affects how Code styles are named.