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

[Pokechu22 <pok...@gm...>]

Just as a note, the Wikipedia style for these kinds of links is to instead
use a template ({{Main}} <https://en.wikipedia.org/wiki/Template:Main>
among others) to link to the relevant page in an italicised, indented note
below the section header.  These kinds of links may be more obvious than
the links in the header itself.  Linking between articles is definitely
great; it just seems like it's easy to miss these header links.  (An
example of this template in use on Wikipedia is the ASCII
<https://en.wikipedia.org/wiki/ASCII> article)

--Poke

On Sat, Apr 3, 2021 at 5:47 AM John Colket <jc...@gm...> wrote:

> So there!😉
>
> On Sat, Apr 3, 2021 at 8:19 AM Peter Sampson <
> pet...@gm...> wrote:
>
>>
>>
>> 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
>>>>>
>>>> _______________________________________________
> Audacity-quality mailing list
> Aud...@li...
> https://lists.sourceforge.net/lists/listinfo/audacity-quality
>