Re: [libreoffice-documentation] Draft Proposal for a 6.x Guides Template

2018-11-19 Thread Dave Barton
On 19.11.2018 16:02, Dave Barton wrote:
> 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.

OK scratch that. While running some more checks I picked out the
published ODT chapter GS6000 Preface, searched for character style
LOMenuPath and the extension fell over. So back to my workaround.

Dave


-- 
To unsubscribe e-mail to: documentation+unsubscr...@global.libreoffice.org
Problems? https://www.libreoffice.org/get-help/mailing-lists/how-to-unsubscribe/
Posting guidelines + more: https://wiki.documentfoundation.org/Netiquette
List archive: https://listarchives.libreoffice.org/global/documentation/
Privacy Policy: https://www.documentfoundation.org/privacy


Re: [libreoffice-documentation] Draft Proposal for a 6.x Guides Template

2018-11-13 Thread Dave Barton
Hi Cathy,

Thanks, your comments and observations are much appreciated.

It's getting late here and I need a bit of time to accurately formulate
my replies, so I will answer in the next 12-18 hours.

Regards
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:
>> Another "little" LO Documentation task I set for myself over the weekend
>> was to draft a proposal for a template for the 6.x series guides, which
>> I have now completed and uploaded to:
>> https://nextcloud.documentfoundation.org/f/81381
>>
>> Basically my draft is only an adaptation of Jean's original LO6.0
>> template. My draft is liberally scattered with comments, some in
>> response to Jean's original comments.
>>
>> 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.
>
>>
>>    * Wherever possible I have used "Document Properties" and other
>> fields
>>  to automate the updating of documents.
>>
>>    * 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?
>>
>>    * 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 create some kind of boilerplate outline to be used.
>
> I imagine that most people look at the guides for help with particular
> issues. From looking at the table of contents, they can see what is
> contained in each chapter.
> Thus, I am not sure that there is a need for more introductory
> information at the beginning of a chapter.
>
>   * For the benefit of seriously color vision impaired people (like
>     myself) I have changed the background and text color of the
>     "Caution" heading. To you color vision perfect folks who find this
>     change glaringly obnoxious, I say do what I have to do every day,
>     "/live with it/".
>
> I think the Caution heading looks fine.
>
> by the way, when I initially downloaded the document from Nextcloud,
> the orange background of the Caution banner was not visible, so the
> yellow text was not readable. I just tried it again and the orange
> banner is visible. Perhaps this was a LOO glitch.
>
>  * Jean's original comment proposed increasing the Numbering styles
>     beyond 3 levels. Checking through previous guides I can find no
>     evidence of where we have needed or used numbering levels beyond
>     level 3. My proposal is not to add more levels.
>
> I am not clear about what Jean was referring to when she indicated
> that list numbering should be revised.
>
> Where possible, I have cut back on the numbering/bullet levels, as I
> think they are sometimes not needed and make the text look cluttered.
> I am not sure that there is a need to add more levels.
>
>  * Jean's original comment proposed that we describe various levels for
>     "Mixed Lists". Again, after checking through previous guides I can
>     find no evidence of where we have needed or used mixed lists. My
>     proposal is to not 

Re: [libreoffice-documentation] Draft Proposal for a 6.x Guides Template

2018-11-12 Thread Cathy Crumbley

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:

Another "little" LO Documentation task I set for myself over the weekend
was to draft a proposal for a template for the 6.x series guides, which
I have now completed and uploaded to:
https://nextcloud.documentfoundation.org/f/81381

Basically my draft is only an adaptation of Jean's original LO6.0
template. My draft is liberally scattered with comments, some in
response to Jean's original comments.

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.



   * Wherever possible I have used "Document Properties" and other fields
 to automate the updating of documents.

   * 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?


   * 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 create some kind of boilerplate outline to be used.


I imagine that most people look at the guides for help with particular issues. 
From looking at the table of contents, they can see what is contained in each 
chapter.
Thus, I am not sure that there is a need for more introductory information at 
the beginning of a chapter.

  * For the benefit of seriously color vision impaired people (like
myself) I have changed the background and text color of the
"Caution" heading. To you color vision perfect folks who find this
change glaringly obnoxious, I say do what I have to do every day,
"/live with it/".

I think the Caution heading looks fine.

by the way, when I initially downloaded the document from Nextcloud, the orange 
background of the Caution banner was not visible, so the yellow text was not 
readable. I just tried it again and the orange banner is visible. Perhaps this 
was a LOO glitch.

 * Jean's original comment proposed increasing the Numbering styles
beyond 3 levels. Checking through previous guides I can find no
evidence of where we have needed or used numbering levels beyond
level 3. My proposal is not to add more levels.

I am not clear about what Jean was referring to when she indicated that list 
numbering should be revised.

Where possible, I have cut back on the numbering/bullet levels, as I think they 
are sometimes not needed and make the text look cluttered. I am not sure that 
there is a need to add more levels.

 * Jean's original comment proposed that we describe various levels for
"Mixed Lists". Again, after checking through previous guides I can
find no evidence of where we have needed or used mixed lists. My
proposal is to not define any "Mixed Lists" styles.

I don’t have a sense of the need. We can always create a style if needed, but 
perhaps Jean knows of some instances where this would be helpful.

 * I have added a comment in reply to Jean's original comment regarding
"Simple Lists" which should be self evident.

I am not clear about the need for this style. Why wouldn't simple bullets be 
used?

 * Likewise, the "Text Body Intro" style might have some value if the
the