search

opengeospatial / sensorthings

The official web site of the OGC SensorThings API standard specification.
132 stars 28 forks source link

SP edits for publiction #123

Closed ogcscotts closed 3 years ago

ogcscotts commented 3 years ago

final edits by OGC staff for publication

hylkevds commented 3 years ago

Interestingly, quite a few of these edits have no influence on the resulting document, they only format the source: Line breaks in a paragraph are removed in the compile step, double-line-breaks are turned into a single one.

Since Git works on a per-line basis, shorter lines means shorter, and easier-to-read diffs. Hence my tendency to put a line break after each sentence. When a change is made, only the changed sentence is shown in the Git-Diff, not the entire paragraph. Double-line-breaks before a new heading also makes the source easier to read.

Does OGC have a policy about this?

ogcscotts commented 3 years ago

Most of the changes to extra line breaks are to compensate for some issues we have seen in the past with Asciidoctor’s PDF conversion. For instance, bullets need an extra line break between the sentences and at one time, extra line breaks between paragraphs or headers got reflected in the output. I believe that the latter is corrected, but I have old habits.

I remove line breaks in paragraphs to help with future tagging of content that we will be using in our content management system to block text to be pushed to various “views” of the Standards. We will be creating some more formatting guidance as we finalize the design of the “implementer-friendly” view of our Standards.