New Chapter Template for LO24

Documentation LibreOffice Guides
#41

By dividing the guides into documents for each chapter, we manage to structure their content and allow several collaborators to work separately and without using so much content. Each chapter is structured into sections. These sections allow us to assemble the chapters into a master document to generate a complete guide in its formats: ODT, PDF and HTML. Although some sections do not seem to be necessary for the ODT or PDF guide, these are essential for the HTML format. Each chapter must necessarily have the following sections:

Sections for HTML formatting

SEC_LOGO
It is used for the LibreOffice logo.

SEC_GUIDE
Used for the name of the guide and its version

SEC_TITLE
Used for the title and subtitle of the chapter

Sections for all formats

SEC_DISPLAYAREA
Used for the entire content of the chapter

SecciĂłn SEC_COPYRIGHT
This is a second level section and should be contained within the SEC_DISPLAYAREA section. It is used to indicate licenses, collaborators, basic information about the guide and the table of contents.
This section is shown in the separate chapters but is not shown in the full guide. The complete guide has its own section for Copyright.
This section can be hidden (in the entire guide) or shown (in separate chapters) by using the book variable. It is set to be hidden with the book eq 1 condition.

Section names should not be changed arbitrarily, because those names are used to generate the guide in HTML format.
Recommended reading: Writer Guide, Chapter 16

1 Like
#42

Thanks for the advice Antonio.

I will be using it.

Regards
PeeWee

#43

Hi All,

As this thread increases in length, I’m a little reluctant to introduce more ideas. However, these points are fresh in my mind following recent work on the Base Guide – if I don’t write them down now, I won’t remember them. And apologies if any are covered in earlier posts in the thread.

  • For the Body Text paragraph style, ticking the “Do not split paragraph” option can leave unnecessary white space at the bottom of the page before a longer paragraph. Consider unticking by default, allowing paragraphs to split across pages?
  • For the LO User Guides table style, consider changing the Text Flow properties so that the first row is assumed to be a repeat heading by default. In our guides, this seems a more frequently occurring case than a table that does not have a repeating header row.
  • In my recent work I’ve seen several cases where a table caption appears at the bottom of one page, with the remainder of the table on subsequent page(s). This isn’t a great look. Can we consider ticking the “Keep with next paragraph” option for the paragraph style that we recommend for table captions? (Possibly also for the listing caption style, but not for the figure caption style).
  • If you enter one or more characters and then superscript them using the Format > Text > Superscript option, Writer considers this to be direct formatting. Can we consider including a character style for superscript?

Regards,

Steve

#44

Hello Steve

Hopefully the following answer some of your questions as they do create good book format when followed. Good book format also requires position adjustment for some figures and the use of cross references.

The “Do not split paragraph” is selected or “Allow to split paragraph” is not selected to help prevent blank spaces from appearing. However, the following writing rules have to be used:

  • No more than six sentences per paragraph. If necessary, the occasional paragraph can have more than six sentences to create a better understanding of the paragraph contents.
  • Sentences should not be longer than 25 words. If necessary, the occasional sentence can have more than 25 words to create a better understanding of the sentence contents.

For ordered and unordered lists, there are similar rules.

  • List items should only consist of a single sentence not longer than 25 words.
  • If necessary, a list item can have more than 25 words to create a better understanding of the item contents.
  • The occasional list item can have more than one sentence to create a better understanding of the list item.

All the above are from Simplified English standards that I have worked with. They are designed to help users whose mother tongue is NOT English and make English text easier to translate into other languages.

For tables, the LO Table style has to be used. However, Table Properties have to be adjusted to create good table format.

  • In Table, tables are centrally aligned and the table width is reduced to 90% relative.
  • In Text Flow, “Allow table to split across pages and columns” is selected.
  • In Text Flow, “Allow row to break across pages and columns” is deselected.
  • In Text Flow, “Repeat Heading” is selected and 1 is set in “The first rows”.

Captions for table and code listings use the paragraph style ”Caption” are left aligned at the top of a table or code listing.

Captions for figures use the Figure paragraph style are centrally aligned below the image and inside the figure frame.

I will look at adding a superscript and subscript character styles into the template for LO user guides.

Regards
PeeWee
LO Documentation Team

#45

As I have mentioned repeatedly, the captions are assigned by Writer with their corresponding paragraph styles.

The Caption paragraph style is a parent style and as such is intended to modify child styles generic properties and should not be applied except in rare cases.
The Caption style has left alignment if you want to change the alignment of a specific object (table, image formula etc.), you must do it in the corresponding style. (Table, Figure, Formula etc.)

A writer does not have to worry about changing paragraph styles for different captions.

  • When a caption is inserted into a table, Writer creates the paragraph with the Table style.
  • When you insert a caption into an image, Writer creates the paragraph with the Figure style.
  • When you insert a caption into a listing, Writer creates the paragraph with the Listing style.
  • When you insert a caption into a formula, Writer creates the paragraph with the Formula style.

Why do we have to change the style of a table caption to Caption?
Why do we have to change the style of the caption of a listing to Caption?
Why do we have to change the caption style from a formula to Caption?

#46

I don’t agree with not split the paragraphs.

When at the bottom of the page there is no space for a paragraph of six sentences, let’s say there is only space for 4 sentences and the next paragraph has six sentences, there will be a large empty space at the bottom of the page.
This situation forces us to separate the paragraph of six sentences with a paragraph break in one of the sentences, which breaks the discourse we want to achieve.

I have only seen this type of separation of sentences from paragraphs in legal documents.
In literature, paragraphs usually have many sentences and in printed editions this application is very rare; orphans and widows are normally used to break paragraphs between pages.

I think that the use of no split the paragraph is not intended to be done in a generic way, perhaps it is advisable in some isolated case, in a certain style, but not in the Body text style.
Maybe in some list styles?

#47

Hi Peter,

I too have worked on successful documentation projects where Simplified English was required, primarily for export customers.

I understand the arguments for and against and do not wish to get involved in discussion about them.

However, as I update a guide, I will continue to attempt to attempt to write understandable content but will NOT start counting words and sentences to decide how to break things up.

Regards,

Steve

#48

OK Steve

I am using my experience of being an international technical after working with all European languages, except Gaelic and Welsh, to create the LO Chapter template. However, I am taking notice of the comments made to further improve the template before releasing a new version for approval.

Regards
PeeWee

#49

Hello Antonio

I am using my experience of Simplified English and working with all European languages to create a template format. Not splitting paragraphs does help in creating a good format for technical user guides that most LO users can easily understand, especially if their mother tongue is NOT English. Also, it helps having a basic English text ready for translating into another language.

Regards
PeeWee

#50

Hi Peter and All

I am also working on a new template, I hope to have it finalized next week and I will upload it to Next Cloud. In this template I do not detail the application of the styles nor does it have examples like in the previous templates, it only has a summary of their use and some explanation of special styles.

In my template I try to compile the attributes of all the styles used, so that if a style error is seen, there is a starting point to correct it and it can also be easily transferred to other languages.

#51

OK Antonio

I shall go through your document and then use all the useful suggestions.

Regards
PeeWee

#52

I don’t know who approves or disapproves the templates, if there is a consensus or if it is just one person who decides.
I just want to clarify that they are not just suggestions, it is not merely a document. It is a template with the styles included and will be ready to carry out the relevant tests and modify it if necessary.

#53

Hello Antonio

You are not the only who does not know how a template is approved - single person or a consensus of the LO Documentation Team. At the moment, it looks like it is only the two of us working on the template. Hopefully our messages are read by another volunteer who can help.

I am going to use your idea of using the Writer paragraphs for Table, Listing and Figure to format the captions. All three types will inherit the style attributes from Caption, except for Figure. The figure caption will be centrally positioned under the graphic image to create a good format. This way of formatting the position of a figure caption has been used in the many documents I have created using various international standards.

However, I have come across one problem which is when an example of code listing is used in a document. A block of text cannot have a caption added like a table or figure. My solution is to create a single cell table with no borders then insert the code example into the blank table cell. The option “Allow row to break across pages and columns” has to be selected in the Table Properties dialog to allow for long code examples being placed into a user guide. The listing caption can then be added above this single table cell.

Regards
PeeWee

#54

I think that the text of the code listings should not be entered into a table. I think the solution for these cases is already explained in the last templates.

1- Create a table above the list
2- Insert the legend for the table
3- In the Insert Caption dialog, choose the Listing category
4- Delete the table.
When deleting the table, The cross-reference is not deleted, which is what we need to reference the listing in the guides.

The Writer guide explains the table trick to insert a legend into a formula (I don’t remember where)

#55

Figure must also inherits the attributes from Caption. You can change the attributes of Figure to center the caption. This affect to all figures but no at tables, listings etc. and the same for the rest of captions styles.

  • The Italic style of the caption has not efect in images or frames.
#56

Hello Antonio

I am already using your suggestion as it is the easiest way to handle captions.

Regards
PeeWee

#57

Hell Antonio

I used this method in a previous version of the template, but is a little messy. Using a single cell table with no borders is a very easy solution and works very well. I have been doing some testing this morning to find a simpler solution to code listing.

Regards
PeeWee

#58

The change in the names of the styles for grammatical reasons has forced us to review the template. It’s been good because I think we’re going to create a new template using the Writer styles philosophy better.

These changes are going to give us a lot of work in reviewing/updating the guides.
We must rationalize and minimize the introduction of changes as much as possible.

The way to insert legends in code listings is already established, works properly and there are quite a few listings that would need to be changed (Work added).

I think your idea is not bad, but it should be discarded based on productivity.

#59

Hello Antonio

What do you mean with this paragraph:

"The way to insert legends in code listings is already established, works properly and there are quite a few listings that would need to be changed (Work added).”

Could you please send the method that is already used.

Regards
PeeWee

#60

-I think that is the method used until now, established in the templates that have been used until now, (I couldn’t tell you since when)

With Work added I meant that using this new method for listings means more work for guide revisions/updates.

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