Chapter Template 24.x proposal

Documentation LibreOffice Guides
#1

Hi
I had a look at the current template and uploaded a draft for the next LibreOffice 24.2. The file is an normal ODT file that we can turn later as template. On the cloud it is

LibreOffice Documentation/English/Contributor Resources/Proposal-Template-24.odt

The changes suggested are

  1. The Headings color was made darker to address accessibility.

  2. Remarks on Text and Alt Text for images for the same accessibility

  3. Remark on Character styles and “Reset to Parent” property to allow attribute inheritance of the surrounding paragraph style.

  4. Numbering 3 paragraph style indentation

Some remarks on Accessibility

I’m not an expert in accessibility but here are my findings

  • Perfect accessibility may not be realistic. For example, characters styles are not welcome as they “convey additional meaning”.

  • Text and Alt text in images are hard if done manually in dozens of images. However I have a script that copies the caption to the Text and Alt Text properties and that can silence accessibility checker until a better text is written there.

  • There is need to change the colors in code listing because of the low contrast

Please add your comments here and to the file so we can get a consensus.

Cheers
Olivier

#2

Hello Olivier

I do have one suggestion for the template is to change the paragraph alignment to centre for figure captions. The reason for this is to help when compiling the user guide from the chapter files. To explain:

As you add chapters to a user guide, the figure numbers automatically increase. This increase in figure number adds characters to the caption increasing line length. Very often the increase in line length for a caption creates a two line caption, which increases the overall height of a figure frame. The result is large empty spaces appearing in the user guide pages and that does not look professional.

Also a long caption under some figures with left paragraph alignment can make the figure look a little unprofessional when a single line caption extends beyond the right side of an image or graphic. It is better to use a centre paragraph alignment so that a long caption extends evenly on both sides of the figure frame.

Obviously, changing paragraph alignment will probably mean that separate Caption Figure and Caption Table paragraph styles would be required. For tables, a left aligned caption looks professional at the top of a table.

Any increase in height of a figure frame is easily corrected by increasing width of a figure frame manually when checking a completed user guide.

Is there a method of making a figure frame increasing frame width automatically as you add long captions? I have tried to do this a couple of times, but no success yet.

Regards

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

#3

Hello again

Page Styles comment.

There is one page style missing in my opinion.

A back page style is required for the back cover. This would require the page to be a left page only so that the back cover is correct for a user guide. A back cover appearing on a right page does not look good when a PDF file is created or the user guide is printed.

Regards

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

#5

Hi @peewee

Thanks for the suggestions, I added both caption and back cover topics to the file.

I also added some space (0.3cm) below style Caption Table to add spacing to the table that follows.

I have no solution for the caption length vs frame size. There seems to need a balance between image size and caption length. For example a small image and long caption, or caption that runs from margin to margin doesn’t look good. I also think that images shouldn’t be as wide as margin to margin, but be 90% of that (as we do in tables). It may not be realistic in some case with big images like application screenshots.

Cheers
Olivier

#6

Styles comment
The Code Paragraph Style must have Language = None so that the spell checker does not detect or correct errors since it is a programming language. Also the Code Character Style.

I propose the DejaVu Sans Mono font (supplied with LibreOffice), despite being from a different family, this font has a heavier weight than Liberation Mono and shows better when using the colors for basic syntax highlighting. — I don’t know how it affects accessibility but I imagine it is positive.

I will send more comments as I study the template proposal

#7

Book Template comments and Page Styles of the book.

I have published the Writer 7.5 guide in Spanish. I have used a Master Document (odm) to create the complete guide. I find it easier than copying and pasting the content of the chapters into an odt file. Once the guide is completed it is saved as odt and the work is done
I don’t know how the guides are exported to HTML (whether by chapters or a complete book), in any case I think it is more convenient.

  • Regarding the page styles for the front and back covers of the book

I wonder if it wouldn’t be more appropriate to use the styles supplied by Writer Right Page for the front page and Left Page for the back cover. Since these are images and a text box, it would not be necessary to adjust the page layout of these pages and there would be no need to create new styles.

  • Obviously, the styles in the template for the Master Document must be the same as those in the template for the chapters
#8

Numbered legends in the figures.

I think that the text for the numbered figures should be part of the body of text and not the frame, placing for example the text of the numbered legends in a table of type Contents positioning, for example.
This makes the figures have a homogeneous format and possibly helps the HTML export by avoiding complex legends.

Alignment to centre for figure captions, and Styles of captions

Styles for captions are built into Writer:

  • In the figures we use the Caption paragraph style.
  • When you insert a legend for a table, writer automatically applies the Table paragraph style* (which we don’t use for anything else).
    Modifying these styles would be enough without the need to create other styles, thus simplifying the Custom Styles list.

I think and believe that the captions should be as short as possible, which would not significantly increase the Caption paragraph or the text in Alt and Text properties on HTML.

  • Instead of a legend like “Figure 22: Tab Position an Size of the Frame dialog box, showing vertical alignment to Top of the Base line.”
  • The correct thing would be just: “Figure 22: Tab Position an Size of the Frame dialog box.”.

The extended explanation should go in the body of the chapter text. Centering the Caption paragraph style is optional.

I think to make the frame fit the length of the legend text
The width of the frame must be Autosize and With (at least) it is not important as long as it is less than the width of the image. In the figure you can see a very small size (the one that comes by default when inserting a frame), that small measure prevents the frame from being larger than the image when the legend occupies less than the image.

image
image711×583 34 KB

#9

Hello

Yes, captions should be as short as possible without losing the meaning. However, some captions, although short, are still longer than the width of a graphic/image. Left aligned captions do not provide good format in this situation. Solution for good format is to use central alignment for captions for figures.

When creating a complete user guide, the increase in line length because of an increase in figure number characters can create two line captions. This is not good format. The solution is to increase figure frame width to create a single line caption. Left alignment would look unprofessional. Two more reasons for centre alignment for figure captions.

Captions for tables have to be left aligned for good format. So there is no change for table captions.

Regards

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

#10

I understand that centered alignment can make all figure captions more homogeneous, if the text of some captions is longer than the width of the figure, and I do not dispute this, but I do not see that the length of the figure number has an influence so much.
So since the guide that has the most figures is the Calc guide (518 figures in its latest version). I don’t think a number with just two more characters than the one in figure 1 would substantially lengthen the text of the caption.

The solution to having figure text occupy a single line is to enlarge the width of the frame to fit the caption text, regardless of whether a center or left alignment is used.

#11

Hello Bantoniof

The idea is to have a single line caption creating a good format. It is easy to widen a figure frame manually if a figure caption creates two lines.

When adding separate chapter files into a user guide file does create two line captions. There is an increase in characters in the figure numbers as the figure number increases in the later chapters of a user guide. It is the later chapters in a user guide that are the problem.

Also, there is an increase in page numbers which also creates extra lines in a paragraph because of the additional character added to a cross reference. This also causes formatting problems in a user guide.

Figure captions and cross references are the culprits in creating large blank spaces in a user guide. The solution is easy, but has to be manually carried out by carefully checking the user guide before publishing. Increase the width of figure frames and reposition some figures to remove the blank spaces.

A user guide has to look professional when it is published. Creates a good feeling to users of LibreOffice.

Regards

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

#12

Now I have understood it:

  • The width of the figure frame must be adjusted to the legend text in each chapter.

When joining the chapters in the complete guide, the small variation in the numbering of the figures causes the legends to remain on two lines,
so you have to adjust the width of the frame again to the new length of the legend text.

-The solution is a macro that adjusts the width of the frame and runs it on both the individual chapters and the entire guide.

thanks for the clarification.

#13

Suggestion / question about Code paragraph style.

I don’t know how the HTML language treats tabs, so perhaps the suggestion should be discarded.

The Code paragraph style should have multiple tabs (shorter than Writer’s default) so you can index the code comfortably.
If tabs are not advisable in Html then you have to index with spaces and I don’t know if this is advisable either.

What would be correct?

#14

These paragraph styles appear in the newly released Draw 7.6 guide:
Body Text, Note
Body Text, Indent 2
Body Text, Indented 2
Body Text, List Intro

What is the purpose of these styles that do not appear in the proposed 24x template?

  • They also do not appear in the template LO-UG-Chapter-Template-7-4.ott nor in the template LO-
    User-Guide-Template.ott

(Caption Table Listing also appears but this is in the templates)

OOoComputerCode and Bullet Symbols character styles also appear (I think these are old styles no longer used)

I think that the first step to uniformity of the guides is to have as few user styles as possible and that these are well defined in a template and that template be applied to the chapters, erasing foreign styles.

And what about the sections
SEC_LOGO, SEC_GUIDE, SEC_TITLE and SEC_COPYRIGHT, SEC_DISPLAYAREA ?

#15

Hello Olivier

I have just re-read your email and do agree with your comments about captions.

Figure captions look much better when they are centrally aligned, even when a caption is a little longer than the width of a figure frame. However, the problem is that the frame does automatically expand to prevent the caption from word wrapping. Captions should only be a single line to create a good page layout. I have tried to find an option to set the figure frame to automatically expand its width, but have been unsuccessful. It is easy to do manually when required.

Figure widths should be only be about 90% width of the margin width. Losing 10% width on a dialog screenshot does not affect legibility and is hardly noticeable. Maybe there should be some redesign of dialogs so that the maximum width used is 15cm.

With regards

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

1 Like
#16

I have uploaded a new version of the suggested template to be used for LibreOffice 24 user guide and chapters. The file can be found in LibreOffice > English > Contributor Resources on NextCloud. Please review and let me know any comments or suggestions.

Also note that some paragraph style names have changed to bring them into line with the preinstalled paragraph styles used in LibreOffice, as follows:
Text Note is now Body Text Note
Text Body List Info is now Body Text List Intro
Text Body Indent 2 is now Body Text, Indented 2

Regards
PeeWee

#17

The proposal template is called Proposal-Template-24-3-PS.

Reagards
PeeWee

#18

I have found several relatively minor problems (omissions and inconsistencies) and hope to find time to write a list of them in the next few days, if other people don’t find and report them first.
Jean

#19

There is another thread about the template, opened by Olivier.
I don’t know if this or the other thread can be closed to centralize all opinions in one place.

https://community.documentfoundation.org/t/some-remarks-on-24-2-templates-and-sanity-checks-macros/
I have uploaded a file with some inconsistencies that I have seen:

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