Updated LO Chapter Template for user guides

[PeeWee]

The first draft of the LO chapter template for user guides can be found in the Contributor Resources folder on NextCloud.

The filename is LO-Chapter-Template-7-4-first-draft.ott

Please review and comment.

The following paragraph styles have been added to the template to help in creating a good format for future chapters.

Definition Term 2 - for 2nd level options in a dialog.
Text Body Indent 2 - explanation for 2nd level options in a dialog.
List — this creates a simple list instead of using Text Body Indent and line breaks.
List 1 Cont and List 2 Cont - allows the use of a 2nd paragraph below an item in an unordered or ordered list.
Legend Numbered - creates a legend for text in a figure. This will make it easier to translate the majority of text used in figures.

All paragraph styles, except headings, now have the option “Do not split paragraph” selected to prevent any paragraphs from breaking across pages. This does mean a writing style change to prevent long paragraphs.

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

[flywire]

I've added a couple of comments about code styling as previously discussed
in
https://listarchives.libreoffice.org/global/documentation/2022/msg00445.html

They are small changes but I think they would improve useability and
consistency. I'd like to discuss them.

Regards

[flywire]

The following is extra explanation of some of the comments about the code
style.

1. While computer code works on lines, word processors work on paragraphs,
so code lines are entered as paragraphs in the guides. Code lines often
extend past the width of the display device and are wrapped to the next
line. Conventionally, wrapped lines have the same spacing as other code
lines. That is how they are displayed in other documents and that is how
readers expect to see them.

It is not logical to have extra spacing below paragraphs in the code style
when they are paragraphs of the same style. The option should be selected
not to display it. Keeping code together reduces the splits across pages
making it easier to understand, and listings take fewer pages to support
the concepts in the guide.

2. Code is processed in lines but there is no standard line length. I'm
aware of the python code standard PEP 8 using a maximum of 79 characters on
a line. This is likely based on the old 80-character wide terminals, still
a common default for terminal windows.

The Code paragraph style (Liberation Mono, Regular, 11pt) allows 71
characters on a line. Code character styles in LibreOffice guides commonly
use both 10pt and 11pt. At 10pt 78 characters can fit on the line with an
inner and outer margin of 2.5cm and 1.8cm respectively. Increasing code
paragraph width by 0.3cm to allow for 80-character lines would probably be
worthwhile, but at least by 0.05cm to allow 79 characters.

3. Listing captions give them a brief description so readers can more
easily understand their purpose and allow them to be referenced.

[flywire]

Can you work with the text below?

   1. Paste it into the document as unformatted text (to ensure there are
   four characters before 2nd and 3rd lines).
   2. Follow:
   https://wiki.documentfoundation.org/Documentation/DocumentationTeamInfo/ProducingLibreOfficeUserGuides#How_to_for_syntax_highlighting_code

def open_greeting(args=None):
    # Code lines with a maximum length of 80 characters will not wrap over
line
    print("Hello World" + 1 * "!")

The second line, exactly 80 characters long, is intended for testing and as
a point of discussion about font size, line length, and line spacing. If
more testing is required I'd suggest the Base Guide 7.3, Chapter 8 Macros,
close_form, the second-last macro in the chapter. Some longer lines would
need adding to test wrapping.

Regards

[PeeWee]

Hello Flywire

I have changed to the template and the info about the Code paragraph style as follows. Also, I have used the code example that you sent me.

The following is an example of code. Please note that lines of code are generally a single line of text that normally do not line wrap. When samples of code are entered into a LibreOffice document, there maybe some line wrapping due to the constraints of line width caused by margins.

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

[flywire]

The changes look about right, with the exception of the comment line's
missing 's' as the eightieth character, but the template styles need more
work.

1a) Code End paragraph style is not required and should be removed
(approved
https://listarchives.libreoffice.org/global/documentation/2022/msg00391.html)
because
extra line spacing below paragraphs now occurs when paragraphs change.

1b) The code explanation would be better placed after the code to
demonstrate the extra space which isn't obvious before a heading.

2. Code syntax character styles should be added to the template and linked
to the code style. If the styles exist in the document the macro will use
them rather than creating new styles not linked to the code style. The
example code had 5 character styles which have been replaced with user
formatting, bypassing the main template purpose of enforcing consistent
styles. We look forward to a better solution being developed (
https://listarchives.libreoffice.org/global/documentation/2022/msg00341.html
),

Following
https://wiki.documentfoundation.org/Documentation/DocumentationTeamInfo/ProducingLibreOfficeUserGuides#How_to_for_syntax_highlighting_code
adds OOoComputerCode to the document. Possibly (??) the only change needed
is deleting it and changing _OOoComputerBase character style to inherit
from Code. I've previously suggested the lo palette colors should be used.

3. These changes are probably best tested by someone that hasn't been
formatting code for the guides. To avoid all sorts of anomalies I have
hacked the extension and changed the styles, and I'm not confident I've
fully reset it to what others get after deleting the lodev version config.

[PeeWee]

Hello Flywire

The only character style in the chapter template is Code, which is Liberation Mono 10pt. The Code character style is listed in Character Styles on Page 6 in the template.

However, in the example of code that has been used there three colour character styles used - green, blue and red. What are these character styles called in the programming language? Using the same names in the chapter template for character styles would be good.

The code explanation paragraph has been placed below the example. That was a good suggestion.

Adding the “s” at the end of the line in the code example has caused it to wrap. The explanation paragraph has been changed to reflect this.

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

[PeeWee]

Hello again

Just changed the font colour of Code to match the code example you sent me. I got the colour from your example. Will check the other colours used in the example.

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

[flywire]

Should check turning off automatic update of templates is not an issue.