Getting Started Guide 7.6 pre-release - Further look welcome

Hi Team

I spent the last week assembling the Getting Started Guide 7.6 with our best practices (I think). The chapters were reviewed and updated by @jeanweber , @PeeWee , @vladasavy and @rthorn999 .

The book is available in the bookshelf and the documentation website.

  • The chapter were updated and “cleaned” with a series of scripts written by @bantoniof (and I will resume our work ASAP, once we get the final template)

  • Images and frames were renamed on a sequential number scheme based in chapter prefix and order in the chapter.

  • For accessibility purposes, the images have now a alt-text and a description, copied from the caption.

  • Frames were adjusted to images + caption size. In some rare cases, the images were repositioned or resized in the contents to prevent large “voids” in chapter pages.

  • Characters, paragraphs and lists were “cleaned” of direct formatting.

The book was assembled using a master document and a full ODT file was created after the master document.

More readings are welcome to check for mistakes that slipped from my eyes. Announcement will follow soon.

Cheers
Olivier

@ohallot I found several mistakes in chapter 11 Getting Starting with Macros.
Do you want me to send it to you personally or should I publish it here?

@ohallot A very quick look reveals a lot of list numbering problems, some bad page breaks, and some other issues.
Page 60, list starts with 5.
Page 247, bad page break. There are others, but I’m not listing them all. This one would be easy to fix by putting the figure in a different spot in the sequence of steps.
Page 299, list starts with 9.
Page 353, list starts with 4.
Page 356, three paragraphs appear to be styled as figure captions (italics, centered) but should probably be list items.
Page 434, list starts with 8.
Page 494, list starts with 6.
Page 500, list starts with 12.
Page 502, list starts with 15.
There may be others.

@ohallot I think part of the bad page breaks problem is that you have “Add spacing between paragraphs and tables” selected in Tools > Options > LibreOffice Writer > Compatibility, and many (most?) of the chapters were created with that setting deselected. If you change that setting, some formatting problems will go away. The list numbering and paragraph styles will still need fixing, of course.

Hi @bantoniof
First, thank you for the set of scripts you wrote to fix many document issues.

Please can you post here your findings? It will help me to manage.

Cheers
Olivier

For the records, I’m dropping the term “add-on” in the Preface, since it has been replaced by extensions long time ago.
Olivier

@ohallot
This is what I Found:
I have already commented before that my English is not good at all and I apologize in advance.

Problem 1: The indentation of numbered and unnumbered paragraphs (bullets) is not appropriate according to the template
This is a feature (I don’t know if it’s a bug) of Writer and the Direct format cleaning in paragraphs with associated numbering: The cleaning of direct formatting eliminates the direct formatting to the paragraph (indentation, color of the area, etc.) but detaches the paragraph from the style of associated list (although in the style it is still associated).
Since the indentation in paragraphs of this type is a combination of the indentation of both styles, with clean format, the paragraph is left with only the paragraph indentation, not with the sum of the paragraph indentation and the list style indentation.
Consecuence: In the document there is a smaller indentation than those what is configured in the template.
Verification:

  • Go to page 5
  • Go to the end of the introductory paragraph of the first listing (“Use the following steps….”)
  • Insert a paragraph break and change the style of that new paragraph to Numbering 1. The indentation is those of the template. - This is also applicable to bullets listing (page 12).
    Solutions:
  • Leave it as it is because it is surely uniform in all documents (???)
  • Adjust it manually or using one of the macros that I have provided you (ask me if this is the option)

Problem 2**:** The text that refers to macros, in the middle of a body text paragraph, has a small font size. You can see it at point 2 at the end of page 8 “Double-click the HelloMacro subroutine in the Object Catalog ……”).
-This is a problem with the definition of the Code character style in the template used.
The issue has already been mentioned in other posts but has not been solved. Character Styles - #11 by bantoniof and LO Chapter Template 7-4 - #60 by bantoniof
Solution:

  • Reset to parent Style the Code character style
  • Change the Font to the neccesary (Liberation Mono), but without changing the size it acquires.
  • Check in the Position tab the Character spacing (must be – 0,5pt).

Of course, you have to modify the template and apply it to the rest of the files.

Problem 3: On page 7 there is a blank space that occupies half a page
Solution: If figure 3 and figure 4 are made smaller so that they both fit on page 7 the space would remain (on page 8) but considerably less

Problem 4: figure 8 on page 14 of chapter 11 of the Getting Started Guide It’s not an image. It is a table, within a frame with a shadow, within the frame that also contains the legend. This format is quite strange, since the frames are designed for figures.
Solution: I think it would be better to have a table (without a frame) or take a screenshot of the table to convert it into an image.

HI @jeanweber
Thanks. I have set the compatibility options to none for all files.
Olivier

@bantoniof
Problem 1: We agreed that there is a bug with lists in version 7.6 an beyond (159366 – List styles add paragraph direct formatting on loading Writer document)
Problem 3: Fixed
Problem 4: left as is.
Olivier

PS: Files uploaded.

@ohallot Looking at the latest PDF and ODT for the book, I see these problems, which include a lot of lists NOT restarting at 1:

  1. Lots of comments are in the ODT, I assume in the chapter files, that have not been removed. All about checking the list numbering.
  2. Footers in the TOC shows Getting Started 7.5, not 7.6.
  3. Page 28, List starts with 8.
  4. Page 58, List starts with 5.
  5. Page 143, List starts with 4.
  6. Page 165, List starts with 5; second list on page starts with 7.
  7. Page 204, List starts with 5.
  8. Page 205, First list starts with 8; second list starts with 11.
    I give up… there are LOTS more. Chapter 6 in particular seems to have many pages where all the lists are numbered sequentially instead of restarting. You need to recheck the entire book.
  9. Page 301, Some of the list items under item 3 probably should be numbered 4, 5, 6, etc instead of what they are. Also, the final item in that list is numbered 11.

Hi @jeanweber

Thank you for the second reading of the published book.

With respect to the lists numbering, the solution was supposed be restarting numbering each offending list on each chapter, right?

Wrong. :slight_smile: :slight_smile: :slight_smile:

I hit a bug on lists where no matter I set the restart flag, on reload the chapter, the restart numbering flag vanished. I had to manually recreate the first list item, and check if the restart flag was maintained. The bug may be related to 159366 – List styles add paragraph direct formatting on loading Writer document

I think the numbering is OK now.

The extra comments were all cleared.

The footer of the book is fixed.

Cheers
Olivier

@ohallot While preparing a copy of the book for the print edition, I found a few more errors.
Page 243, Figure 182 legend is a list; it starts with 4.
Page 318, in Step 7 (under Fig 273), legend is a list that starts with 5.
Page 320, in Step 9, list starts with 7.
Title pages for chapters 4, 6, 7 have a missing LO version number. This is due to those chapters have a spelling error in the field name in the Custom Properties.
Lots of bad page breaks, probably not worth fixing now so I’ve not listed them, but should be fixed for next release. Many have left a lead-in paragraph or minor heading at the bottom of a page, with the list or other text on the following page. Others have left large white spaces where moving a bit of text could fix it.

I also noticed a LOT of grammatical errors, typos, etc. All are minor and the sort of things that spellcheck and grammar check are unlikely to find, so I think all chapters need a good edit during production of the 24.x edition, in addition to the technical review and update.

Regards, Jean

@ohallot I have corrected the errors for the print edition and published it on Lulu, here:

@ohallot Oops! I just found some missing x-refs: four of them on page 214. Should be referring to Figures 151 and 152. I will fix the print edition.

Hi Jean
I’ll review these errors this week.
The Lulu link is in the documentation website. Thank you for that.
Olivier

I hope I caught all list misnumbering for good. I had to manually set the restart numbering in paragraph direct formatting dialog and also set start number to 1.

Missing references corrected

Some bad page break fixed. Maybe not all.

About the grammatical errors, we need support of skilled native speaking volunteer. But I’d like to have a few samples to understand.

Cheers
Olivier