Hi Cathy, all,
Sorry I haven't replied sooner, but I have been out of action for almost
a week and no docs work, or most anything else, during that time.
I am trimming my replies down to just the salient points.
Dave
On 13.11.2018 03:50, Cathy Crumbley wrote:
> Hi Dave,
>
> Your revision of the template is quite helpful. Some of my thoughts
> follow below.
>
> Cathy
>
> On 11/5/2018 4:55 PM, Dave Barton wrote:
>> So what changes are proposed? The main points are:
>>
>> * The question of image anchoring within a frame remains open. It may
>> be that we have a need for 2 different anchors for electronically
>> published chapters/guides and another for (Lulu) paper printed
>> guides.
>
> We should agree on how to handle this. I suggest talking about this
> Wednesday.
Sorry I couldn't make the meeting, but it would be good if we can can
find a workable compromise. It seems this issue has been creating
difficulties for some time [1].
>
>> * In 2 of Jean's original comments, she makes valid
>> recommendations to
>> have additional character styles (LOMenu Path and LOKeystroke) for
>> the possible requirement of style changes in future guides. I
>> propose removing these additional styles because our documentation
>> revision time frame does not really justify these extra styles and
>> they only serve to complicate guide style formatting and confuse
>> contributors as to when and which style to use. For a little
>> simplification, I am proposing these character styles be removed
>> and
>> the identical default "*Strong Emphasis*" and "/Emphasis/"
>> styles be
>> used instead.
>
> I wonder about eliminating the Keystroke and MenuPath styles. This is
> for two reasons:
>
> 1. While you are concerned about adding those styles, the guides are
> already using them. My understanding is that AltSearch does not find
> character styles, so changing those styles could be time consuming.
> 2. As I believe Jean has mentioned, eliminating these two character
> styles (by replacing them with Emphasis and Strong Emphasis, which
> it sounds like have the same properties) prevents them from being
> used in a future redesign.
>
> Perhaps I don't understand well enough why you propose eliminating
> these styles. Do you see clear benefits to reducing the number of styles?
My workaround for the AltSearch extension has been to run it in AOO,
where it functions perfectly. Today I have been following the 6.2 QA bug
hunt and I decided to install and check out the AltSearch extension.The
good news is that I had a 100% success rate searching for various
character styles in 25-30 randomly selected documents.Hopefully this is
not a fluke and the extension will work under 6.2 for everyone.
My motivation for a new (redesigned) template is twofold:
1. Simplification. For new documentation contributors there are already
enough "/mental gymnastics/" and "/gotchas/" to work out, as you
recently discovered with the question of indexing. Any small things
we can do to make contributing easier has to be a move in the right
direction. From the reader's perspective it is of no interest
whether or not the correct style has been applied to a visually
identical aspect of a document, he/she only wants clear readable
information.
2. Standardization: The more we work with modified in-built
(standard/default) styles the easier it will become apply our
template to updates of the documentation. Having renamed variants of
the in-built styles only creates additional work. This is the
situation we currently faced with in the Calc guide, where the last
published edition was for LO 4.1 created with a template riddled
with OOo and other renamed style references. Had we tried to stay
with in-built and standard named styles in the past our styling
workload would now be substantially reduced. Yes, there will always
be the need for an exception, but the more we standardize the easier
our future workflow will become.
As for future changes of documentation design, please go to ODFAuthors
and grab a copy of any ODT file for OOo 3.0 (published 2013). Ignoring
the colors and the naming convention used, everything is
(unsurprisingly) pretty much identical to our present day publications.
Which suggests that Jean and other contributors of the day got the basic
outline correct and I have not read any proposals for a major deviation
from that outline for the future.
>> * Our current guides give little information to the reader about the
>> content/layout of the chapter/guide, So I have inserted a new
>> section, which includes macOS/other OS key equivalents, moving it
>> fro the "Copyright" page. Here I leave it to contributors to decide
>> what Information might be most useful to readers in understanding
>> what the chapter content/layout provides, although it might be that
>> we could
