Better identifiers

The Book feature described in the previous post relies on identifiers for Chapters, Sections and paragraphs. Now let see how to set an identifier in a Part file. Paragraphs have special identifiers in the sense they must be unique inside the whole Section, not inside the whole Book. But the semantic must remain the same -- just use a different marker. Decorations (additional information) for a Chapter / Section can take place right below the element.

*** My Chapter
#some-identifier-here

[Sections and paragraphs follow]

But Paragraphs don't have nested elements so the nesting rule is somewhat violated. Decoration for a Paragraph must look like this:

§some-paragraph-identifier
This is my paragraph.

Placing the decoration above the Chapter / Section delimiter would be consistent but I find it less readable:

#some-chapter-identifier
*** My Chapter

#some-section-identifier
=== My Section

§some-paragraph-identifier
My Paragraph.

There is another feature I never talked about: Tags. This is for adding even more decorations to those elements.

#some-chapter-identifier
@Tag-one @Tag-two
*** My Chapter

#some-section-identifier
@Tag-one
=== My Section

§some-paragraph-identifier
@Tag-three @Tag-four
My Paragraph.

That seems pretty unreadable now but the case above is not realistic. And indentations can be added to differenciate decorating stuff. Real-world example rather looks like this:

  #some-chapter-identifier
@Tag-one @Tag-two
*** My Chapter

  #some-section-identifier
  @Tag-one
=== My Section

  §some-paragraph-identifier
  @Tag-three @Tag-four
Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Pellentesque
tortor justo, blandit at, tincidunt sed, blandit et, dolor. Donec pede
massa, cursus sed, ornare et, volutpat non, mi. In pede. Nullam
hendrerit tellus vitae justo. Etiam et massa in dolor scelerisque
faucibus. Praesent libero ante, ultrices eu, egestas ac, interdum in,
dolor. Phasellus sit amet tellus eget metus ultricies suscipit. Nam sed
neque sit amet neque gravida bibendum. Cras elementum. Suspendisse
potenti.

I definitely don't like decorations above Chapters and Elements. Let's see how it looks when placing them below:

*** My Chapter
  #some-chapter-identifier
  @Tag-one @Tag-two

=== My Section
  #some-section-identifier
  @Tag-one
 
  §some-paragraph-identifier
  @Tag-three @Tag-four
Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Pellentesque
tortor justo, blandit at, tincidunt sed, blandit et, dolor. Donec pede
massa, cursus sed, ornare et, volutpat non, mi. In pede. Nullam
hendrerit tellus vitae justo. Etiam et massa in dolor scelerisque
faucibus. Praesent libero ante, ultrices eu, egestas ac, interdum in,
dolor. Phasellus sit amet tellus eget metus ultricies suscipit. Nam sed
neque sit amet neque gravida bibendum. Cras elementum. Suspendisse
potenti.

That's definitely better. Let's say that Paragraph identifiers is a marginal case. Let's say that it's pretty uncommon to have identifiers for Chapters and Sections because if you want to pick the whole Chapter it's unusual to pick some Sections inside. And let's avoid identifiers whenever possible : that will reduce bloat and do less typing. Let's say a Section / Chapter title can be referenced as an identifier when unique in the whole Book scope. The ::add syntax supports almost any character so a title with spaces and nested text (like parenthesis) is ok. Now let's do the mix:

*** My Chapter
  @Tag-one @Tag-two

=== My Section
  #some-section-identifier @Tag-one

  §1
Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Pellentesque
tortor justo, blandit at, tincidunt sed, blandit et, dolor. Donec pede
massa, cursus sed, ornare et, volutpat non, mi. In pede. Nullam
hendrerit tellus vitae justo. Etiam et massa in dolor scelerisque
faucibus. Praesent libero ante, ultrices eu, egestas ac, interdum in,
dolor. Phasellus sit amet tellus eget metus ultricies suscipit. Nam sed
neque sit amet neque gravida bibendum. Cras elementum. Suspendisse
potenti.

That looks pretty readable to me.