Definition Lists proposal

[anuvyklack]

I tried to use markdown, orgmode and will be happy to use neorg to store brief descriptions of keybindings and options of different software. Over time I found that the best formats for this are Vim-help files and Linus man files.

The options and keybindings descriptions are indented from the edge of the page and aligned along the left margin. So it is easier to find with eyes the desired item and then read its description.

It would be brilliant if neorg will have the same feature

The extended Markdown has Definition Lists, which can be used for inspiration.

The main difference is that in Definition Lists the description should always start from the next line, while in vim-help and linux-man formats it could start on the same line if its enough room. And I don't know if markdowns Definition Lists allow include other constructions such as list and code blocks inside description, which will be super cool to have.

Pictures with examples of what I mean

[vhyrro]

Yup, this sounds like a good idea. Soz for the late reply btw. I'm down to implement this, but we need to be pretty strict in the decisions we make. Here's some of the things we gotta consider:

• We probably won't be able to implement the "definition list on the same line in the same way vim-help formats do it". Neorg simply does not have any rules for such modifiers to exist and creating an exception simply for a single element of the format is not something worth doing :(
• Because of the above, we will need to follow the markdown method and create a definition for an item on the next line. I have three generic ideas for this very syntax, feel free to talk about it:

Idea 1. Using a character to denote a definition:

SVG
^ Scalable vector graphics

The `^` character would be used to denote a definition for the element above.

Idea 2. Using a carryover tag:

$define SVG
Scalable vector graphics

Idea 3. Repurpose drawers and change them to be a definition instead:
|| SVG
  Scalable vector graphics
||

The second and third idea (especially the third) give us a lot more flexibility because they allow lists and code blocks to exist within the description just as you said you'd like. I think I like the 3rd idea the most, whaddya say? Paired with future snippet support and other goodies writing a lot of these in rapid succession would be pretty easy and nice to look at with the correct highlights.

[mrossinek]

I am very much in favor of the third proposal 👍

[anuvyklack]

How about the third variant but with double colons?

There are also 4 variants where double colons signs could be:

1. First line of the description -- last line of the description

   Lorem ipsum
   ::	Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do
   	eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim
   	ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut
   ::	aliquip ex ea commodo consequat.
   

2. First line of the description --- next after the last line of the description

   Lorem ipsum
   ::	Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do
   	eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim
   	ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut
   	aliquip ex ea commodo consequat.
   ::
   

3. Definition item line --- last line

   :: Lorem ipsum
   	Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do
   	eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim
   	ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut
   ::	aliquip ex ea commodo consequat.
   

4. Definition item line --- next after the last line

   :: Lorem ipsum
   	Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do
   	eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim
   	ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut
   	aliquip ex ea commodo consequat.
   ::
   

As for me, the first variant is the most convenient.

[vhyrro]

Those are cool ideas that are similar to other formats but there's a few problems that we need to take into account:

• In neorg, things aren't really arbitrary. There's something that strikes me as a bit odd with the :: syntax and that is how Neorg does things in its philosophy - "if applicable, always use one character before you start thinking about two". The double || syntax exists because | is already occupied. This issue can be circumvented if we give : a real meaning first, then we could start worrying about :: :)
• Regarding the third proposal, I know that writing

<paragraph>
:: <definition>
<stuff>
:: <last line>

Is convenient and fast but then you lose things like single-line definitions. How would I do:

<paragraph>
:: <definition on one line>

? I couldn't.

• As for the second definition it looks nice in my opinion but then we lose consistency (making consistent file formats is hard 😭). We lose consistency because all detached modifiers should change the look of the document in-place or should change the look of the following text. This means that having to look back on a previous paragraph and change the meaning of that previous paragraph because we had a definition on the next line is not really something we do. This is why we have things like carryover tags that go above a heading vs org drawers that go below a heading. It also means that my previous idea of ^ is completely inapplicable too.
• I personally think the fourth looks nice. The issue as i described above though is that a single : has no meaning, which means we would have to occupy that to do something too. Adding something forcefully though just to cram in another syntax element isn't something that's great either, so we need to find some sort of balance in that regard :)

[vhyrro]

@mrossinek and I also came across the idea to do this:

: Definition
Lorem ipsum dolor sit amet

This part is no longer part of the definition.

And also:

:: Definition
   Lorem ipsum dolor sit amet
  
  This definition spans across multiple paragraphs
::

A single : would mark a single-paragraph definition, aka the text below the definition can only be a single paragraph. Anything else is no longer counted as part of that definition. A double :: would signify a ranged definition and would allow you to place markup inside like code blocks, lists etc. Wdyt?

[gzagatti]

Definition lists are great for technical documentation. The use of colons for defining description lists is well-established in other formats. The idea above looks very clean.

[mrossinek]

Definition lists are great for technical documentation. The use of colons for defining description lists is well-established in other formats. The idea above looks very clean.

Actually we ended up settling on the syntax described above but using $ instead of :