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.
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
Light grey highlighting colour added to Code paragraph and character styles.
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.
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:
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.
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.
Inserting, position and captioning figures has changed to improve the formatting of a user guide. Please read the instructions.
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.
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.
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
Comments added to LO-UG-Chapter-Template-7-4-20220819.ott.
I note a comment @jeanweber put on each Calc7.4 guide code listing caption:
Hello
Setting keep with next paragraph for the Caption paragraph style could cause formatting problems. A figure caption is placed at the bottom od a figure. Keep with next paragraph could make the figure jump to the next page if the figure is placed at the bottom of a page.
I suggest new paragraph caption style for Code Listing. That way keep with next paragraph could be set.
Regards
Peter Schofield
psauthor@gmail.com
Technical Writer, LO Documentation Team
Is the Updates to Extensions Available tool on the menu bar documented? I didn’t see it in guide screenshots.
It is subtle but should be checked if any extensions are used to produce the guides.
Table captions also need to be Keep with Next. Perhaps a new paragraph style should be called Table/Listing Caption?
Jean
There is an Extension Manager for installing extensions and updating any extensions, but no Updates to Extensions Available tool.
Just tried using a frame and it is easy to add a caption to the frame. Using Insert Caption on a selected frame allows you to add a text caption. You can change the beginning of the caption to match a code example — Listing 1: Code Example. The numbering is automatic and it can be placed at the start of a code example inside the frame. The only drawback is if the code example is too long to fit on one page, but then you could always split the frame.
Solves the problem. Any thoughts.
Peter Schofield
psauthor@gmail.com
Technical Writer, LO Documentation Team
Hello Jean
I agree with that one. Two caption paragraph styles — Table/Listing Caption and Figure Caption. Easy enough to set up.
I am chatting to flywire about this one and found a possible solution. Use a frame and a text caption. A text caption you can change Text to Listing.
Regards
Peter Schofield
psauthor@gmail.com
Technical Writer, LO Documentation Team
The Updates to Extensions Available tool on the menu bar is only shown if old extensions (ie not current version) are installed. It saves running the Extension Manager Check for Updates.
The pros and cons of frames were discussed in Computer Code Caption - English - Ask LibreOffice with the main outcome being frames are not practical for inserting code snippets given they can span pages. The other concern is reducing the functionality of the code. There are enough issues now getting code from a pdf document into a programming environment and retaining layout as much as possible without complicating the container. Normal paragraphs with left-aligned margins give the best result.
Hello
A possible solution to frames for code is use a frame for only the caption. A little fiddly, but works as follows:
Insert a frame above the first line of code and set the width to 16.5 cm and height to a minimum of 0.25 cm.
Right-click in the frame and select Insert Caption to open Insert Caption dialog.
In Category, enter the word Listing.
In Caption, type in the caption title.
In Numbering, make sure Arabic (1 2 3) is selected
In Position, select Start from drop-down list, then click OK.
Caption will appear in the one line frame. Change paragraph style to Caption Table Listing.
When cross-referencing to a code listing, Listing appears in Type in the Field dialog. This solves the problem of referring to code examples.
This can easily added to the template.
Peter Schofield
psauthor@gmail.com
Technical Writer, LO Documentation Team
What is the benefit of a frame? The Calc guide seems to manage all the issues except keep with the next paragraph without a frame.
Many of the caption attributes are used differently. Keep with the next paragraph is only appropriate if the caption is above the content, eg tables and listings but not figures, and the extra paragraph between the listing caption and content is not appropriate but reflects a view white space is required. The calc guide also seems to successfully include references in the captions without a frame.
