Improve spec line numbering

[Dan Bonachea]

The line numbers in the current spec document are ugly and not very helpful. They globally number every single line in a running count from the start of the document. They number every single line, with no regard to paragraphs or (occasional) empty lines. The numbering includes non-prose objects like title page elements, TOC, section headers and images. The numbering inside floats reflect their location in the .tex sources, instead of their position in the formatted document. Insertion of any line anywhere in the document globally perturbs line numbers for everything subsequent in the document.

ISO specs usually number each paragraph of prose and reset the count within each section. This makes it very easy for external text to refer to a specific text via section.subsection-paragraph (eg C99 5.1.2.3-p2), in a way that is far less likely to be perturbed between spec revisions.

We should deploy similar paragraph-level numbering to get the same benefits.

Ideally code examples longer than 5 lines also have their own internal line numbers (starting from 1).

I don't think the lineno latex package can do this, but other packages exist.

[Scott Baden]

It appears that whatever solution we come up with, that to implement this enhancement it will necessary to modify the complete set of source documents so that a special macro call will be placed before each paragraph we want numbered. This is how the ISO C++ standard handles it (via a special iso package, https://www.ctan.org/pkg/iso)

https://github.com/cplusplus/draft

There found a number of other ad-hoc solutions but they all required a special macro call before each paragraph.

I have some limited testing on our spec, cobbling together what the C++ standard uses, but I have by no means tested it exhaustively yet.

If we decode to go with this solution, we will should probably draft a small group of 3 us to get it done quickly. Incremental updates will get messy with many other pull requests as we start to process other spec issues that are getting resolved at the same time.

[Dan Bonachea]

This issue was triaged at the 2018-06-13 Pagoda meeting and assigned a new milestone/priority.

Fix is in-progress and should appear in the upcoming release.

[Dan Bonachea]

issue #65: paragraph numbering and format factorization

Deploy paragraph numbering globally and enable it by default. Enable internal line numbers for code examples.

• Add p{itemize,enumerate,description} environments that add pnums to \items

• Add new plstlisting environment that inserts a leading paragraph number and sets the language style to upcxx

• Add a numlisting environment that adds internal line numbers to inline code

• Factor repeatedly used function specification text into macros:

\progresslevel{X} "UPC++ Progress Level: X" \precondition "Precondition: " \permituninit "This function may be called when \upcxx is in the uninitialized state." \concepts "C++ Concepts: " \uconcepts "UPC++ Concepts: " \ordering "C++ memory ordering:"

Each includes an automatic \pnum

• Add a completions environment that formats completion items

• Add manual \pnum to all normal paragraphs

• There are NO changes to normative text in this commit, only formatting.

Resolves issue #65

→ <<cset 756ded8b4d37>>

[Scott Baden]

Touché!

Scott