Re: [Audacity-quality] Manual: Section Header Consistency

[Peter S. <pet...@gm...>]

On Sat, Apr 3, 2021 at 12:18 PM Peter Sampson <
pet...@gm...> wrote:

>
>
> On Sat, Apr 3, 2021 at 12:02 PM John Colket <jc...@gm...> wrote:
>
>> As long as it is by design - I thought it was simply a typo.☺
>>
>>
> That's fine John - these things are worth considering (and reconsidering)
> from time to time.
>
> And is is worthwhile to ensure that our style guide covers the bases - so
> Connie will get
> updated later today.
>

Connie has spoken:
https://alphamanual.audacityteam.org/man/Consistency#H1_heading

Peter.



>
> BTW, I never considered for a moment that a section header would also
>> double as a link  I thought I had already arrived at the relevant
>> information that I had been looking for...
>>
>
> A good example is the top level Macros page:
> https://alphamanual.audacityteam.org/man/Macros
>
> which is designed as a helicopter view with brief sections on
> 1) Manage Macros
> 2) Macros Palette
> 3) Macros Examples
>
> All of those could be on a single page but it would be a long indigestible
> page
> and we tend not to favor overly long pages by and large.
>
> Peter.
>
>
>
>> - John
>>
>> On Sat, Apr 3, 2021 at 4:56 AM Peter Sampson <
>> pet...@gm...> wrote:
>>
>>>
>>>
>>> On Sat, Apr 3, 2021 at 8:34 AM Peter Sampson <
>>> pet...@gm...> wrote:
>>>
>>>>
>>>>
>>>> On Sat, Apr 3, 2021 at 12:54 AM Pokechu22 <
>>>> pok...@gm...> wrote:
>>>>
>>>>> That's because the first one is just a regular header (== Time Scale
>>>>> Zooming (Horizontally) ==), but the second one has a link in it (==
>>>>> [[Vertical Zooming]] ==).  They're at the same heading level (and
>>>>> thus have the same font size and boldness); the color is only from the link.
>>>>>
>>>>> I don't know what Audacity's style guide is for these (it does seem to
>>>>> be used in several places on that page at least), but Wikipedia discourages
>>>>> them (see https://en.wikipedia.org/wiki/MOS:NOSECTIONLINKS - though
>>>>> that doesn't elaborate on why they aren't recommended).
>>>>>
>>>>
>>>> Frankly, speaking as the primary Manual editor, I am not too concerned
>>>> with Wikipedia's
>>>> policy on this *(except when I am editing Wikipedia as a minor
>>>> Wikipedian)* and see no need
>>>> to slavishly follow Wikipedia's style guide in our Audacity
>>>> documentation.
>>>>
>>>> I use links in headers to aid users - I do that to make life easier for
>>>> them.
>>>>
>>>> I will have a look later today to see what Connie (our style guide)
>>>> says about this, *but*
>>>> *she may end up ruling in favor  ;-)*
>>>>
>>>
>>> Basically Connie currently has no ruling one way or the other about
>>> links in headers:
>>> https://alphamanual.audacityteam.org/man/Consistency#Layout
>>>
>>> I do note that she says:
>>> > Generally, we stick to Wikipedia guidelines
>>> <http://en.wikipedia.org/wiki/Wikipedia:Naming_conventions_%28capitalization%29>
>>> for page titles.
>>>
>>> But:
>>> a) note that applies specifically to "page titles (and we observe that)
>>>
>>> b) note carefully the use of "Generally" which allows for some
>>> occasional flexibility
>>> if and when thought about.
>>>
>>> She's going to ponder the headings with links issue today, but I'm
>>> suspecting that
>>> she'll come down in favour of allowing such links ( for a start there
>>> are many of those
>>> scatterd throughout the Manual.
>>>
>>> One of the reasons that I, as editor, like these headers with links is
>>> that is is a clear visual
>>> cue to the reader that there is a page or section elsewhere in the
>>> Manual that contains a
>>> lot more detailed information then the text they are currently reading.
>>>
>>> One of the underlying design features of the Manual is that it rests
>>> heavily on the use of
>>> hyper-text with thousands of links throughout the Manual - starting, of
>>> course, with Bill's
>>> "*Amazing Image-map*" that we have on the front page (acting
>>> effectively as a "Contents"
>>> directory).
>>>
>>> Peter.
>>>
>>>
>>>
>>>
>>>>
>>>> Peter.
>>>>
>>>>
>>>>
>>>>> --Poke
>>>>>
>>>>> On Fri, Apr 2, 2021 at 4:44 PM John Colket <jc...@gm...> wrote:
>>>>>
>>>>>> These two manual links should be at the same heading level, but
>>>>>> display in different colors on Chrome:
>>>>>>
>>>>>> https://manual.audacityteam.org/man/zooming.html#horizontal
>>>>>> https://manual.audacityteam.org/man/zooming.html#vertical
>>>>>>
>>>>>> - John
>>>>>>
>>>>>>
>>>>>>
>>>>>> _______________________________________________
>>>>>> Audacity-quality mailing list
>>>>>> Aud...@li...
>>>>>> https://lists.sourceforge.net/lists/listinfo/audacity-quality
>>>>>>
>>>>> _______________________________________________
>>>>> Audacity-quality mailing list
>>>>> Aud...@li...
>>>>> https://lists.sourceforge.net/lists/listinfo/audacity-quality
>>>>>
>>>> _______________________________________________
>>> Audacity-quality mailing list
>>> Aud...@li...
>>> https://lists.sourceforge.net/lists/listinfo/audacity-quality
>>>
>>