Replies: 9 comments 7 replies
-
|
BTW definition lists should probably be renamed e.g. "key-value list" or "itemize list" since in my experience they are more often used for other things than strictly definitions of terms/glossaries. |
Beta Was this translation helpful? Give feedback.
-
|
In HTML 5 it is called description list, it got renamed from the HTML 4 definition list. |
Beta Was this translation helpful? Give feedback.
-
|
These are some interesting ideas. I can see the use of having But I'm curious what you think about reStructuredText's idea of having two distinct concepts: definition lists and field lists. Note that field lists can contain block-level content via indentation. In djot, a field list would, essentially, ust be a list where the markers are distinct field names. These wouldn't replace definition lists (because of the restriction on field names); it would be a distinct concept; but these seem better suited for metadata. |
Beta Was this translation helpful? Give feedback.
-
|
Do you mean that djot would use that exact syntax for field lists? I sense ambiguity with symb syntax! |
Beta Was this translation helpful? Give feedback.
-
|
If we used the same syntax we might need to rethink symb. But I was really wondering more about the concept than the syntax. |
Beta Was this translation helpful? Give feedback.
-
|
What would be the semantics? Presumably definition list is the real definition list, and field list is for meta, which doesn’t have any specific display representation (it’s up to converter to interpret meta, default converter might just omit it from output, or display in an unspecified way)? To me it does seem worthwhile to syntactically distinguish the two. While we can re-use definition lists, I think this might be confusing for users. syntax-wise, both asciidoctor and restructured text use |
Beta Was this translation helpful? Give feedback.
-
|
reST uses field lists in two main contexts:
We don't need this for attributes, so there's the question how a field list would render outside of a metadata context. In rST a field list that isn't metadata or attributes renders as a table with class field-list. One option would be to do what pandoc does and allow metadata fields to be specified anywhere in the document; in this case, they'd just accumulate. |
Beta Was this translation helpful? Give feedback.
-
|
The If it makes sense to use two markers for def list item and def list definition, the first thing that comes to my mind is: And here that is in a tighter format: where the spaces around the |
Beta Was this translation helpful? Give feedback.
-
|
I like this. It is easy to remember, read and write.
Sendt fra min Mac Mini via Apple Mail
… Den 20. jan. 2023 kl. 03.53 skrev John Gabriele ***@***.***>:
The ; and : are extremely similar looking. I think it would decrease readability to have them together where the reader needs to tell them apart.
If it makes sense to use two markers for def list item and def list definition, the first thing that comes to my mind is:
apple:
= Grows on trees. Pick them in the autumn.
orange:
= Round. Comes in an orange color.
pineapple:
= No pine involved here. Nor apple for that matter.
And here that is in a tighter format:
apple:
= Grows on trees. Pick them in the autumn.
orange:
= Round. Comes in an orange color.
pineapple:
= No pine involved here. Nor apple for that matter.
where the spaces around the = are required for two reasons: (1) to disambiguate it from {=highlight=}, and (2) for readability.
—
Reply to this email directly, view it on GitHub <#193 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AGGLXRVOQH65YCAVH3JAWZDWTH4Y7ANCNFSM6AAAAAAT4ABYQU>.
You are receiving this because you are subscribed to this thread.
|
Beta Was this translation helpful? Give feedback.
-
|
I had a similar requirement for Logseq that currently uses Markdown + a custom syntax for key-value pairs. I recently suggested to it the following Markdown-ish syntax that could be adapted to Djot if you are interested: https://discuss.logseq.com/t/an-idea-for-a-more-standard-markdown-property-syntax/20073 Example: Rendered:
|
Beta Was this translation helpful? Give feedback.
-
|
AsciiDoc has a different take on Definition lists (which they call description lists) https://docs.asciidoctor.org/asciidoc/latest/lists/description/ Basically, you write them like this Key:: Value
Key 2:: Value 2
Key with children::
child::: This is a child
child::: This is also a child, note that there are 3 colons; indentation does not matterMight not fit with the rest of Djot, given its a "repeating character" based delimiter, but it does provide a pretty convenient interface for writing lists. Interestingly enough, Kramdown and PHPMarkdownExtra have an almost inverted approach to how Djot handles definition lists |
Beta Was this translation helpful? Give feedback.
-
|
Yes, that PHP Markdown Extra behavior is used in many markdown variants, including pandoc. A disadvantage is that there's no marker at the beginning of a block that lets the parser know we've got a definition list. |
Beta Was this translation helpful? Give feedback.
-
|
I fully agree with the original idea. I would just like to make a suggestion regarding the labeling. The "@" symbol is quite expressive and relatively rare in regular text. Even its basic semantics "at" is very appropriate for our case - what the descriptions refer to. The biggest plus is that the proposed structure is completely equivalent to a regular list. By the way, descriptions without a term are also very popular as explanations and generalizations. |
Beta Was this translation helpful? Give feedback.
-
Examples? |
Beta Was this translation helpful? Give feedback.
-
|
Sorry, I meant similar cases in extended Markdown, where a construction like I know that in HTML it is incorrect to use a list of descriptions without a term, but HTML, unlike Markdown, has enough other means of style design. In regular text, indentation is used not only to separate paragraphs - that's why users resort to this kind of "violation". A block of quotes is also a bad replacement, since they have their own semantics, completely different from descriptions. Perhaps such construction should have its own interpretation? |
Beta Was this translation helpful? Give feedback.
-
|
I don't think semantic constructions like definite lists should be abused just to get an indented paragraph. If you want an indented paragraph, and you don't want it to be a block quote, then maybe attach an attribute to it, or put it in a special div with an attribute, and style that using CSS or a filter. |
Beta Was this translation helpful? Give feedback.
-
Below are some thought I have about definition lists. I have been a bit reluctant to come forward with them, but have decided to do so anyway in light of recent discussion in #35. It is also relevant to #192.
I think djot definition lists should take a hint from the MediaWiki definition list syntax, where both terms and definitions have an explicit marker:
Transferred to djot, where multi-line definitions and nested lists should be possible this becomes something like
I think this is preferable because
it becomes immediately clear which is a term and which is a definition because both have a specific marker,
it should be easier to parse, I think.
not least it allows for more than one definition per term, which is a possibility I would like to have.
the term and definition(s) being at the same indentation level reduces indentitis in nested lists (although this is a minor concern!)
Of course djot might want to use different markers, or reverse them, to preserve some backwards similarity but I think the colon at the start of a definition and the semicolon at the start of the next term makes a nice pair.
A possible compact definition list syntax?
I’ll venture out on a limb here; what follows is nowise an essential part of this proposal, just a possibile extension with (I think) still simple rules. Note that I still have my doubts about compactness as a goal in itself!
If there is a rule that terms may not contain any unescaped colons (or: no unescaped colons with whitespace on both sides!) a “tight” one-line syntax becomes possible e.g. in metadata (#35):
but it should of course be possible to mix this with the multiline/spaced syntax! The rule would be that a semicolon at the start of a line, with/without indentation, would mark the start of a term, and any following inlines not containing any unescaped colon (but presumably allowing
{:symb:}and inline verbatim) would be the term. If the term is followed by/[ \t]+\:[ \t]+/on the same line inlines up to the next blank line are the (only) definition. If the term is followed by a blank line and the next line starts with an unescaped colon on the same indentation level everything, including indented blocks, up to a block starting at the same indentation level is a definition. It may be followed by more such definitions up to another term on the same indentation level, or a block not starting with a colon/semicolon on the same indentation level, which will be the first block after the definition list:Beta Was this translation helpful? Give feedback.
All reactions