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.
Hi Team
I raised the issue in the Calc guide thread, but it worth to be discussed here for the 7.4 Template and the master document.
For the Default page style, we need to define what goes on even and odd pages (beside the page number).
Even pages: [pageNumber] | <????>
Odd pages: <????> | [pageNumber]
where <????> is to be defined.
IMHO, on even pages, <????> would be the chapter number + chapter title
On odd pages <????> would be the current heading reference.
Example:
Even: 34 | Chapter 2 Entering, Editing, and Formatting Data
Odd: Entering data | 35
Is that right?
Olivier
Hello Olivier
I agree with you and this method I have used before for user guides.
Odd page reference should be Heading 1 Paragraph Style followed by the page number. For example Using area fills — Page 11
Not sure if the word Page should be included as the present format used is also good to use, but there must be a visible division between the page number and the reference.
Regards
Peter Schofield
psauthor@gmail.com
Technical Writer, LO Documentation Team
Hello
I will look deeper into this as some of your suggestions are good. Need to learn more about captioning and cross referencing.
Regards
Peter Schofield
psauthor@gmail.com
Technical Writer, LO Documentation Team
To be able to reference the chapter name in the footer, it is necessary to redefine the Chapter numbering in Tools - Chapter Numbering as follows:
Level 1
Numbering: None
Paragraph Syle : Title
Character style: none
Show Sublevels: 1
Level 2:
Numbering: None
Paragraph Syle : Heading 1
Character style: none
Show Sublevels: 1
This setting can go to the template, I think. I did it for the Cac Guide 7.4 master document.
Note: For level 1, we can even replace “Chapter n” in the title by changing to “Numbering: 1,2,3” and fill the “Before” entry to "Chapter " (only if you want to reorder the chapters in the book actually, or leave it as is)
To apply the reference in the footer:
Insert - Cross reference, then Document tab.
On even pages:
Chapter → Name and Level=1
On odd pages:
Chapter → Name and Level=2
Regards
Olivier
