Proposal: Numbered Sections in the specification

[nicholst]

This issue raises two distinct but connected issues.

In #400 work on the pdf rendering, each section has to be treated as a "Chapter" and is explicitly given a "Chapter ?" number. As we already number the Appendices, and as it common for standards to have explicitly numbered sections to make it easier to reference different sections, I would like to propose that use numbering. This can be activated during the PDF rendering, but apparently also with the HTML rendering? (see here).

Secondly, as the PDF rendering is based entirely on the section header labels, it does not match the mkdocs HTML, left-panel navigation menu. Below is the comparison between the labels used in the left-nav HTML (left col) and the section headers (right col).

I propose these should be revised to agree exactly, and going forward require they are the same, to consistency between navigation and the headings, and between perceived navigation (HMTL) and PDF navigation.

Thoughts?

 - Introduction                                        |Introduction
 - Common principles                                   |Common principles
 - Modality agnostic files                             |Modality-agnostic files
 - Modality specific files                             |
   - Magnetic Resonance Imaging                        |Magnetic Resonance Imaging data
   - Magnetoencephalography                            |Magnetoencephalography (MEG)
   - Electroencephalography                            |Electroencephalography  (EEG)
   - intracranial Electroencephalography               |intracranial Electroencephalography  (iEEG)
   - Task events                                       |Task events
   - Physiological and other continuous recordings     |Physiological and other continuous recordings
   - Behavioral experiments (with no MRI)              |Behavioral experiments (with no MRI)
 - Longitudinal and multi-site studies                 |Longitudinal studies with multiple sessions (visits)
 - Extending the BIDS specification                    |BIDS Extension Proposals
 - Appendix                                            |
   - Contributors                                      |Appendix I: Contributors
   - Licenses                                          |Appendix II: Licenses
   - HED                                               |Appendix III: Hierarchical Event Descriptor (HED) Tags
   - Entity-table                                      |Appendix IV: Entity table
   - Units                                             |Appendix V: Units
   - MEG file formats                                  |Appendix VI: MEG file formats
   - MEG systems                                       |Appendix VII: preferred names of MEG systems
   - Coordinate-systems                                |Appendix VIII: Preferred Names of Coordinate Systems
 - Changelog                                           |Changelog

[nicholst]

The differences identified are now resolved as part of #422.

This leaves open the issue of section numbering... interested in what @Arshitha and @sappelhoff thinks of adding number, and in particular if CSS can be used to add numbering as described in https://stackoverflow.com/questions/19999696/are-numbered-headings-in-markdown-rdiscount-possible/21126615

[sappelhoff]

The differences identified are now resolved as part of #422.

I think this is an important point, that improves congruence between PDF and HTML (and makes sense just in general consistency terms).

This leaves open the issue of section numbering.
As we already number the Appendices, and as it common for standards to have explicitly numbered sections to make it easier to reference different sections, I would like to propose that use numbering.

I also think section numbers would be a nice addition.

• As you point out: It's common in specifications and we already have it in the appendix
• It would thus be consistent to also number the sections outside the appendix
• The appendix is currently numbered manually ... it'd be cool to have this done automatically upon rendering

That being said: If there is no easy solution for this, it would not give me a headache to ignore section numbers in the HTML.

This can be activated during the PDF rendering, but apparently also with the HTML rendering?

In the PDF rendering we opted for it because it currently produces the most stable result, and I think we should have the labelling in the PDF regardless of our decision on the HTML.

[nicholst]

Yes! Agree numbering would be good to have in PDF regardless!

Just a quick question: Can we / are we using custom CSS? Just wondering if the HTML numbering solution in that stackoverflow link is a non-starter or not.

[sappelhoff]

just to have a quick (but only maybe helpful) answer: I think we can use custom CSS.

This link might be helpful: https://stackoverflow.com/questions/48029165/is-there-a-way-to-make-the-headings-sections-and-subsections-numbering-in-markd

@effigies knows more about extending mkdocs with css.

[effigies]

Yes. Add a CSS file here: https://github.com/bids-standard/bids-specification/tree/master/src/css

And add an extra_css entry similar to:

bids-specification/mkdocs.yml

Lines 7 to 8 in 245860d

	extra_javascript:
	- js/jquery-3.4.1.min.js

So something like:

extra_css:
   - css/numbering.css