Can someone confirm the process in:
https://wiki.documentfoundation.org/Documentation/DocumentationTeamInfo/ProducingLibreOfficeUserGuides#How_to_for_syntax_highlighting_code
Issues:
* macro should just set colors without altering style
* red and green as the predominant colors is a poor choice for
https://en.wikipedia.org/wiki/Color_blindness
* keywords highlighted within function names is suspect
* inconsistent end of line characters
* random large text
Why has this unnecessary macro operation been added to chapter 2 of the
"Producing LibreOffice User Guides"?
We already have a perfectly good "Code" style in the 7.2x template. If
the docs team feel the style needs changing/improving then let's simply
agree on a revision of the template, not by adding more complexity to
documentation production.
Can you comment in terms of experience formatting code in the guide? I
previously commented code colorization should be part of the style running
any macro behind the scenes. It isn't (ie changing the template does
nothing). If you look through the guides you'll see a lot of inconsistency
from random processes.
1. Extension configuration is not specified anywhere
2. The code style does not color the text, it's done externally or maybe
using this macro
3. The extension also styles text which can conflict with the
documentation style
4. The hotkey description would be better replaced by a link.
The whole process is pretty poor. On top of that, copy/paste doesn't work
in pdf -
https://listarchives.libreoffice.org/global/documentation/2022/msg00295.html
Please note I am subscribed to this list, so it is unnecessary to send a
duplicate post directly to me.
Replying in-line.
Can you comment in terms of experience formatting code in the guide?
It is unclear what you are asking me to comment on. My experience of
this project goes back to 2010 and beyond, during which time I have
contributed to a number of guides, I am also one of the authors of the
current 7.x guide template.
I previously commented code colorization should be part of the style running
any macro behind the scenes. It isn't (ie changing the template does
nothing).
As explained below, the "Code" style of the 7.x guide template can be
changed to any Font Color the docs team wish it to be.
I am starting to think we might be talking at cross purposes. I am
talking about a style used in the OTT template used to produce our user
guides and I suspect you are referring the styling of code used to
produce the software. These are two entirely different subjects.
Maybe the use of the term "Code" has led to some misunderstanding. Our
user guides do not contain any usable programming code, but where a
guide needs to explain/illustrate something like one or two lines of
Basic code, the guide author uses the "Code" style as defined below.
If you look through the guides you'll see a lot of inconsistency
from random processes.
Please cite a few specific examples of where the docs team have
overlooked this apparently endless stream of errors and inconsistencies.
1. Extension configuration is not specified anywhere
Please explain what you mean by "Extension configuration". It sounds
like a reference to a software OXT extension, which is something the
docs team have no direct control over.
2. The code style does not color the text, it's done externally or maybe
using this macro
The 7.x guide template clearly defines the "Code" style:
* Font = Liberation Mono, Regular, 11 pt.
* Font Color = Automatic (ie. Black) with no other effects.
* Area = Light Gray 5
All of those attributes, including Font Color, can be changed in the 7.x
guide template.
3. The extension also styles text which can conflict with the
documentation style
So why add an unnecessary possible conflict?
4. The hotkey description would be better replaced by a link.
What has a "hotkey description" got to do with a documentation template
style?
The whole process is pretty poor.
I am sure the entire docs team would welcome an explanation of what we
have been doing so "poorly" over the years.
On top of that, copy/paste doesn't work
in pdf -
The issue being discussed here is about the styling used in the 7.x
guide template used to produce the original Open Document Text files for
our user guides.
https://listarchives.libreoffice.org/global/documentation/2022/msg00295.html
The link you cite one of your own posts complaining about what you
perceive to be defects in the way LibreOffice creates PDF files from ODF
files. This is matter you should raise with the developer and/or QA
teams, since the docs team have no control over this.
Sorry but your macro proposal would provide no additional benefit to the
production of our user guides, but would add unnecessary complications
for our authors.
Two approaches have been used to color code within LibreOffice:
Only the first approach currently meets the objective of supporting LO document style sheets, but it’s clunky. The second option uses pygments, a widely used and actively developed application with higher quality syntax highlighting.
The second option could be developed to meet documentation needs better. It requires:
These changes seem achievable and would enhance the tool for both the documentation team and the broader community.
A fresh branch has removed that issue. This is looking good.
Edit: StarOffice IDE style added in another branch too.
New style colors in development to match Basic IDE. (IDE punctuation varies so has been left black.)
This prerelease version is fully functional.
Code shown in black to blue)Create a document using the LO Chapter Template and run the extension with these options (using appropriate language and note Custom prefix: Code):
Release v2.4.0 · jmzambon/libreoffice-code-highlighter · GitHub is fit-for-purpose for LO guides.
