A whitespace after `tag::` or not?

Hi,
I am revising the following PR:

The main thing is to change the word after method:::

  • Capitalise the first word in the new line after method::xx.
  • Change the imperative (or infinitive) to the third person singular.

While doing this, I see that there are inconsistencies in the use of tags:

  1. `method::`, `argument::`, `section::`, etc.
  2. `method:: `, `argument:: `, `section:: `, etc.
    Which should be reserved?

one question more:
Should they be capitalised? method:: or METHOD::?

1 Like

The parser shouldnā€™t care about spaces there, so it doesnā€™t matter. There isnā€™t a style guide for documentation, but I donā€™t think this makes that much difference to the readability of the code.

2 Likes

Yes, I was never interested in that. However, it is a bit confusing and not pretty to just read and correct these things.

It would be really nice if there was an AI that could do it on command.

I have the impression that capitalizing the keyword helps with reading the help source code since one knows what the tag is and what the text is. But maybe thatā€™s just my eyes.

2 Likes

Thank you for your opinion!

My preliminary conclusions are as follows:

  1. I agree with @smoge that capitalising the keyword helps when reading the help source. However, in the search result, there are fewer uppercase keywords than lowercase keywords. So it seems better to keep them all in lowercase. For typing, uppercase requires extra work, so it is not efficient for whoever is typing the text.

  2. Argument:: and method:: have only a single word, so no space is needed. However, section::, subsection and subsubsection:: can have multiple words, so a space after these section tags improves readability, I think.

2 Likes

Iā€™m new and donā€™t have a strong opinion on these things, but while I agree with those conclusions, I do think generally capitalizing keywords is a good idea, irrespective of the search results (Iā€™m actually not sure what search results you mean here, I apologize if this is somehow obvious to everyone else).
Naively I would think that as long as the help parser doesnā€™t care, there seems to be no reason not to simply find and replace all the tags with uppercase (via regex or whatever), or does that risk creating more problems than it solves?

I can agree with that for things like METHOD:: etc.

Inline tags might become EMPHASIS::distracting:: when working on the help source, thoughā€¦?

hjh

good pointā€¦ although, having done some work in latex, my process there was usually to separate formatting from actual writing; that is to say, the work for which capitalized keywords would be distracting simply isnā€™t the same kind of work for which they would be useful. I think the issues addressed here are mostly of the ā€œformattingā€ kind. I donā€™t suppose people who write whole new helpfiles from scratch do that in schelp files right away? But maybe they do. Just my two cents, anywayā€¦

1 Like

I think that conversation already happened in the past somewhereā€”something like including a schelp plugin for pandoc (wich can be written in lua or haskell).

So something like markdown could be used.

For example, search results from the current build of the latest SC3.14_dev are as follows

  • method::
    • ^method::: 5742
    • ^METHOD::: 1556
    • ^Method::: 2
  • classmethods::
    • ^classmethods::: 469
    • ^CLASSMETHODS::: 168
    • ^ClassMethods::: 158
    • ^Classmethods::: 1
  • emphasis::
    • emphasis::: 13
    • EMPHASIS::: 0
    • Emphasis::: 0
  • strong::
    • strong::: 97
    • STRONG::: 6
    • Strong::: 2

Lower case keywords are preferred.

I think upper case keywords are easier to read, but require the author to hold down the shift key. This reduces productivity.

Currently I have converted them all to lower case.

Using regexp does not always work:
Over the last few days I have noticed that the SC documentation is not consistent in style. Some of the guides and tutorials are written in a consistent style because they are written by one or two authors. However, much of the documentation is not and is missing punctionations, subjects. The first letter of the sentence or the first letter of the explanation is not uniformly capitalisedā€¦ This is very difficult to organise.

The manual should be more detailed at https://github.com/supercollider/supercollider/wiki/Style-Guidelines:-SCDocs and this address should be included in https://doc.sccode.org/Guides/WritingHelp.html.

Thanks, now I get it!
Actually, I forgot about code highlighting earlier, which does what uppercase keywords would do (i.e., visually highlight said keywords), only better (because non-permanently)ā€¦ so this would be an argument in favor of the lowercase keywords (in addition to your already having converted them to lowercase).

1 Like

I had, at one point, started on an org mode exporter for schelp, but I donā€™t remember what condition itā€™s in. That was years ago and Iā€™m moderately sure that I didnā€™t finish it.

hjh

With babel, org-mode would be cool for the code example sections.

Agreeing on any single rule, like whitespace after tag::, will be less likely to take root outside of a more comprehensive set of guidelines for SC docs.

An official style guideline is totally reasonable, and has been beneficial for the SuperCollider and C++ codebase IMO. They would provide a foundation for large-scale cleanup of the docs. They may even motivate someone to make a formatting/linting pipeline for it, and introduce syntax highlighting into the IDE for .schelp files.

A bulk of the effort for making guidelines is in drafting proposed rules and patiently shepherding the contributors over the finish line.

As an aside, I was able to sneak in a fairly wide cleanup of code formatting in help (Class) files, only because we have official guidelines on code. I didnā€™t touch other parts of the docs files because we donā€™t have agreed-upon guidelines and so would have derailed that effort.

EDIT: I see thereā€™s a proposal to work on guidelines in another thread.

1 Like