Comments (5)
There is already the header node, introduced in version 2.0.0 2021-09-03. This node is used to insert titles that don't appear in the TOC.
Did you consider this, or do you think there is still a need for toc_exclude = true
?
from pml-companion.
Did you consider this, or do you think there is still a need for
toc_exclude = true
?
The problem with [header
is that it applies to different elements, not section headings specifically, and there's no way to control the heading level. This node seems to have an equivalent function to AsciiDoc's titles (via .
):
.Code Block Title
[source=ruby]
--------------------
def some_method(x, y)
...
end
--------------------
.Table Title
|=================
| cell 1 | cell 2
|=================
... etc. ...
The toc_exclude
attribute, on the other hand, would ensure that a natural section heading (<h1>
etc.) will be rendered as usual in the document, according to sections structure, but excluded from the generated TOC. So I think it's still needed.
from pml-companion.
I would suggest to proceed like this:
-
Add
TOC_max_chapter_level
as a config parameter. Allows to define which chapter levels are included/excluded in the TOC. Default value isnull
, which means that all levels are included. For example, setting the value to 4 means that all chapters with level 5 or higher are not shown in the TOC. This parameter is already on my to-do list. -
Add attribute
level
to nodeheader
. Allowed values: 2 to 6. Default value: the level of the parent chapter plus 1. Use specific CSS classes for each level (e.g.header-level-2
,header-level-3
, etc.). Maybe we should also useh2
..h6
tags instead ofdiv
tags. -
If, after implementing 1 and 2, there is still a need for
toc_exclude = true
, add this attribute too.
I am a bit reluctant to implement 3 immediately, because:
-
It adds some complexity, as described in your initial message. Child chapters of an excluded chapter would all need to be excluded too in the TOC. But what if a child chapter of an excluded chapter explicitly specifies
toc_exclude = false
? -
If 1 and 2 are implemented, 3 is (probably) not needed anymore.
-
I don't really like the idea of a TOC that hides some chapters.
from pml-companion.
I'll quickly reply, before handing over the PC to the shop for repair...
- Add
TOC_max_chapter_level
as a config parameter.
Definitely needed (like AsciiDoc toc_level
).
- Add attribute
level
to nodeheader
. Allowed values: 2 to 6. Default value: the level of the parent chapter plus 1. Use specific CSS classes for each level (e.g.header-level-2
,header-level-3
, etc.).
If I've understood correctly, you want to use a class to emulate the styles of default headings? But this would only work when there's a stylesheet that defines the styles for h2
..h6
along with .header-level-2
...header-level-6
.
Maybe we should also use
h2
..h6
tags instead ofdiv
tags.
that would be risky, for the user might be trying to enforce a heading level that is out of synch with the document structure (not to mention that include directives work best with free heading nodes where PML determines their level according to their nesting in the final document).
But what if a child chapter of an excluded chapter explicitly specifies
toc_exclude = false
?
Good question. I guess you'd have to make an opinionated choice on this. Either you ignore it because it's the child of a TOC-excluded node sub-tree, putting the document integrity first; or you make an exception for this specific node, assuming that the end user knows what he/she's doing.
- If 1 and 2 are implemented, 3 is (probably) not needed anymore.
I'm not quite convinced about the level
attribute, but I'll need to think it over when I'm not in a rush.
- I don't really like the idea of a TOC that hides some chapters.
Still, it's a standard feature for editorial-level markup languages (DocBook, AsciiDoc, and others). Even pandoc markdown (which generates TOCs) offers a special class to achieve this.
A practical example, when you include a license like Artistic License 2.0, as an Appendix. The Apache license has lot's of sections, sub-sections, etc., but being a legalese contract, you usually only want to keep the main title. Without an attribute to selectively exclude sections, you end up with a huge TOC (where the Apache entries are more than the actual document), or you reduce the TOC depth, sacrificing navigation of the main document.
from pml-companion.
it's a standard feature for editorial-level markup languages (DocBook, AsciiDoc, and others). Even pandoc markdown (which generates TOCs) offers a special class to achieve this.
If it's so well supported in those languages, it means there is a real need for it. So we should consider adding the feature in PML too (even after adding (1) and (2), because they are not a replacement for (3)).
from pml-companion.
Related Issues (20)
- JavaScript Date function fails in user-defined node HOT 2
- Links URL and Relative Paths HOT 7
- Broken Tables in PML 2.3.0 HOT 3
- Problems with [text Node HOT 2
- PMLC: Add Opts to Launch Manuals HOT 3
- Node Repetition via Asterisk HOT 2
- PML Docs: Add Version Info to Ref Man & Create Docs Archive HOT 5
- Why Multiple Heading IDs? HOT 4
- Fatal Conversion Error: [text Inside [title HOT 2
- Resources directory written to '?/.config' when inside Docker container HOT 2
- Resources directory written for non-action commands like help HOT 2
- PMLC v3.1.0 Segfault on Linux HOT 5
- HTML Attributes Ignored on Images HOT 4
- List Enhancements HOT 7
- CSS Option Treats Everything As CSS HOT 8
- Stylesheets Copy-&-Subfolder Prevents CSS Debugging HOT 12
- Parser Inconsistency with Quoted IDs HOT 3
- PMLC 3.1.0 Crashes on Empty [options Node HOT 2
- Delimited Text Syntax and Unbalanced Delimiters HOT 3
Recommend Projects
-
React
A declarative, efficient, and flexible JavaScript library for building user interfaces.
-
Vue.js
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
-
Typescript
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
-
TensorFlow
An Open Source Machine Learning Framework for Everyone
-
Django
The Web framework for perfectionists with deadlines.
-
Laravel
A PHP framework for web artisans
-
D3
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
-
Recommend Topics
-
javascript
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
-
web
Some thing interesting about web. New door for the world.
-
server
A server is a program made to process requests and deliver data to clients.
-
Machine learning
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
-
Visualization
Some thing interesting about visualization, use data art
-
Game
Some thing interesting about game, make everyone happy.
Recommend Org
-
Facebook
We are working to build community through open source technology. NB: members must have two-factor auth.
-
Microsoft
Open source projects and samples from Microsoft.
-
Google
Google ❤️ Open Source for everyone.
-
Alibaba
Alibaba Open Source for everyone
-
D3
Data-Driven Documents codes.
-
Tencent
China tencent open source team.
from pml-companion.