Extraneous space after asciidoc formatting

[dnowacki-usgs]

In reading through the CF Conventions document, I noticed what seem to be extraneous spaces between AsciiDoc formatting and punctuation marks. For instance, consider this text in section 1.4:

Each variable in a netCDF file has an associated description which is provided by the attributes **`units`** , **`long_name`** , and **`standard_name`** . The **`units`** , and **`long_name`** attributes are defined in the NUG and the **`standard_name`** attribute is defined in this document.

I've reproduced the first instance below:

**`units`** ,

Note the space between the bolded, monospaced units text and the comma that follows.

I have found examples between formatted text and following commas, periods, and parentheses. Spaces also sometimes occur after cross-references (using <<>> syntax). In one or two cases I have found an example with a space between a preceding parenthesis and formatted text.

Given the spaces generally don't exist for non-formatted text (e.g., there is no space between the word "document" and the period in the example sentence above), it doesn't seem to be a conscious style decision. It's also not a limitation of AsciiDoc as far as I can tell; after removing some example spaces I built the text locally successfully with asciidoctor.

Would folks be supportive of a PR removing these spaces? Or am I misunderstanding an intentional decision?

[erget]

Hi @dnowacki-usgs , thanks for these ideas - actually we are planning a few hackathons at the upcoming CF Community Meeting and this sounds like it would be well-aligned with cleanup work plus creating / endorsing use of an AsciiDoc style guide. Are you coming to the workshop? Your participation would be very welcome, hybrid or in-person! Otherwise a PR would be useful, as we could use that as a starting point for a syntax cleanup.

[dnowacki-usgs]

Thanks @erget. I signed up for the virtual option, although it will be a stretch for me as I'm 9 hours behind Santander time. I'll try to put together a PR before the conference.

[dnowacki-usgs]

Okay, I have started a pull request that removes extraneous spaces. This addresses spaces preceding .,]) and spaces following [(. I didn't modify anything in the ncdump-ish output code blocks or most other code blocks, although there were a few that I changed—mostly in pseudo code function definitions.

As for a style guide, I didn't see much out there. I was unable to find any black-style automated doc formatters for AsciiDoc. This recommended practices document is among the few I could find for a starting point for a style guide.

[erget]

I like the recommended practices - thanks for the PR! This puts us on good footing for the upcoming hackathons :)

[erget]

Hi @dnowacki-usgs - we're startng our hackathons in a few hours from https://github.com/cf-convention/cf-conventions/tree/386-cleanup-line-breaks-asciidoc - still WIP but you might be interested. Is #382 ready to be merged?

[erget]

The commits in #382 have been merged as part of the merge of #386. Thanks a bunch @dnowacki-usgs !