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

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

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.


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