numbered blocks

[finanalyst]

Continuing a conversation at end of #35.
@thoughtstream said:

Additionally, I'd like to keep count of paragraphs in a block scope so that I could easily implement a numPara block
(I'm planning on numFormula and numTable as additional custom blocks to match up with
numhead, numitem, numdefn, which are specified).

Hmmmmm. Do we need to open a separate issue about this?

Looking at the available standard block types, it seems that
they fall into two categories: those that produce a visible renderings
and those that are effectively invisible in the rendered output:

Visibly Rendered	Invisibly Rendered
=code	=comment
=input	=nested
=output	=rakudoc
=head	=section
=defn	=pod
=item	=data
=para
=table
=cell
=formula

It seems reasonable that every block that produces a visible rendering
should have a corresponding num... version.

On the other hand, I don't think that we can specify that absolutely any block
(visible or not) can be given a num... prefix. If I squint, I can see that
=numsection or =numrakudoc (and even maybe =numnested)
might make some kind of sense...but =numcomment is just silly,
and =numdata positively misleading`.

[finanalyst]

@thoughtstream I had decided to put numXXX as extra custom blocks so as not to change the spec document again. But the idea of other blocks is mentioned.

I agree with the idea of visible and invisible blocks, and that 'num' versions of visible blocks should exist.

I think however that 'cell' should be considered 'invisible' because it is illegal outside of a table, and within a table, if anything it should be rows or columns that are numbered.

Another complexity I was worried about with regard to table/formula is whether or how numbering should be independent or in the same sequence as head.

[finanalyst]

I had to break off before finishing.

First about existing num behavour, as I have interpreted it.

1. numhead is numerated from the top of the document, and the numeration is calculated when the ToC is rendered, which happens even if it is not used in the output.
2. numitem and numdefn are both independently numbered, and the numbering is blocked scoped.

• This has an undocumented behaviour that a sequence,

=numitem a,
=begin section, 
=numitem y, 
=numitem z
=end section
=numitem b

if b has :continue then it will follow from a, and not from z. There is nothing in spec to prevent this, but it works out more easily to have the numeration function block scoped.

Continuing about other numXXX blocks

We could consider that eg Formula & Table are considered by default to be the same as =head1 for the purposes of ToC. But that would mean the numbering would be the same as head, eg

=numhead header # would be 1. header
=numhead2 minor # would be 1.1. minor
=numformula fff # would be 2. fff
=numhead next # would be 3. next

I think most authors would however prefer numformula and numtable to be independently numbered, eg

1. formula 
4. formula
1. table
5. formula

For =numpara, I was thinking that the numbering should be like =numhead and to be calculated only after rendering. (This is not now a problem because I can insert PCells at any point in a rendering to hold data that is calculated after the rendering).

So my thought is that all block-types, except =item and =defn, have orthogonal numerations, implicitly starting at 1. at the start of the document.

However, to provide for some authorial control, it does seem to me that we should have some more metadata options that affect numbering, in addition to :continue, such as :start(3), which would start a new numbering for that block type. Perhaps even ':resetwhich would be the same asstart(0)`.

I have separated out the Numeration class, so that it the Str routine can be sub-classed to provide different numeration strategies other than the default one in the specification.

[finanalyst]

@thoughtstream Further on division of blocks: in addition to visible/invisible, there is a :toc/:!toc by default division.

Blocks included in ToC	Blocks not included in ToC
head / headN	para
table	code
formula	input
custom block	output
semantic	item
~	defn
~	TITLE
~	SUBTITLE

The last two semantic block are special-cased because that is the way Raku documentation is treated, and it does make some sense to treat them specially. But it is not documented in the spec.

I am also not sure about how to classify nested, because it does have a visual effect, and typically starts a block scope

[thoughtstream]

Just a note that, although I definitely consider this issue important,
I won't be able to discuss or address it until at least Tuesday 11 June
as Linda and I are celebrating our 34th wedding anniversary over the
next few days of the King's Birthday long weekend. I hope that letting
it percolate in a background mental process over that break will mean
I can come up with a more useful contribution once I'm back on air. :-)

[lizmat]

@thoughtstream Congratulations. Wendy and I are only seeing our 20th next year. But then again we've been together for 37+ years :-)

[finanalyst]

@thoughtstream congratulations. Corinne and I will be celebrating on July 1.

[thoughtstream]

[Thank-you both for your congratulations. We had a very pleasant anniversary.]

I think however that 'cell' should be considered 'invisible'
because it is illegal outside of a table, and within a table,
if anything it should be rows or columns that are numbered.

So maybe we don’t specify any in-table numbering for the moment.
If there is a later need/request for it, we (or our successors)
can revisit =numcell, =numrow, and =numcolumn for RakuDoc v.3

Another complexity I was worried about with regard to table/formula is whether or how
numbering should be independent or in the same sequence as head.

Tables and formulae should definitely each have their own sequences, independent of headings.
In fact, every separate block type that can be numbered should have its own independent sequence.

First about existing num behavour, as I have interpreted it.

I agree with your interpretation, including the block-scoping of numbered items.

We could consider that eg Formula & Table are considered by default to be the same as
=head1 for the purposes of ToC. But that would mean the numbering would be the same
as head
...
I think most authors would however prefer numformula and numtable to be independently numbered

Agreed. I think that would be what most authors expect...and what they’d want.

For =numpara, I was thinking that the numbering should be like =numhead and to be
calculated only after rendering.

Agreed. Starting from 1 at the beginning of the document. And not block-scoped.

So my thought is that all block-types, except =item and =defn, have orthogonal
numerations, implicitly starting at 1. at the start of the document.

Agreed.

In summary: every =num... block type has an independent numbering.
=numitem and =numdefn are block-scoped and cluster-scoped,
with numbers restarting at 1 at the start of each section,
or after any block of a different type.
All other =num... blocks are globally scoped,
with numbers starting from 1 at the start of the file.

However, to provide for some authorial control, it does seem to me that we should have some
more metadata options that affect numbering, in addition to :continue, such as :start(3),
which would start a new numbering for that block type. Perhaps even ':resetwhich would be the same asstart(0)`.

I think we only need one metaoption, which would set the numbering of the block type to which it
is applied to a specified number (from which subsequent numbered blocks of the same type would then continue).
Maybe: :number, which might be used as follows:

There are two possibilities:
=for numitem :number(0)
You don’t understand binary
=numitem You do understand binary

If you understand binary, there are two further possibilities:
=for numitem :number(10)
You write numbers in base-2
=for numitem :number(3)
You write numbers in base-10

...which would render to:

There are two possibilities:
  0. You don’t understand binary
  1. You do understand binary

If you understand binary, there are two further possibilities:
  10. You write numbers in base-2
   3. You write numbers in base-10

Further on division of blocks: in addition to visible/invisible,
there is a :toc/:!toc by default division.

Agreed, but I’m not sure how this relates to numbered blocks?

I am also not sure about how to classify nested, because it does have a visual
effect, and typically starts a block scope

I don’t have a problem with allowing =numnested.
I can imagine someone using nested blocks to differentiate
examples, and therefore wanting to number just the nested blocks,
in order to refer to those specific examples.

However, this does bring up another issue. If people do want to refer to
numbered blocks within their text, they’ll want to be able to include the
actual number. For example, if they specify a couple of numbered elements such as:

=for numformula
\sum \frac{1}{n^{2}} = \frac{\pi^{2}}{6}

=begin numtable
    =row
        =cell Closed-form rearrangment of terms
    =row
        =cell Taylor's series approximation
    =row
        =cell Newton's method
=end numtable

...then later they’re going to want to be able to say:
“Table X summarizes the most common solutions to Equation Y.”
...but with the correct numbers automatically inserted.

It seems to me that the obvious way to achieve this is to provide
a metadata option that creates an alias to the automatically assigned number
of any numbered block. Perhaps :numalias, which could then be used like so:

=for numformula :numalias<SumInvSqEqnNum>
\sum \frac{1}{n^{2}} = \frac{\pi^{2}}{6}

=begin numtable :numalias<solutions-table-number>
    =row
        =cell Closed-form rearrangment of terms
    =row
        =cell Taylor's series approximation
    =row
        =cell Newton's method
=end numtable

Table A<solutions-table-number> summarizes the most common solutions to Equation A<SumInvSqEqnNum>.

[finanalyst]

@thoughtstream pandoras box!
I do like these extensions. But for the time being, I would prefer to keep them out of the specification. I'm battling to get my tests to pass for the new renderer, and I want to get a working compliant renderer.

[thoughtstream]

@thoughtstream pandoras box!

You mean: full of evil, with only a tiny gleam of hope buried under all the badness? ;-)

It’s no problem to suspend this discussion for now. We can leave the issue open,
and revisit it whenever suits you.