Update documentation to clarify ban of multi-line checklist items (if they are tasks)

[gwww]

Issue tracker is ONLY used for reporting bugs. New feature ideas should be discussed in the ideas section. Please use the Q&A section for supporting issues. Please use the search function.

If you encountered the issue after you installed, updated, or reloaded the tasks plugin, please try restarting obsidian before reporting the bug.

If you want to report a bug, please follow the guide lines below to help me resolve it.

Expected Behavior

Current Behavior

See this thread, with images. https://forum.obsidian.md/t/checklist-with-line-breaks-markdown-rendering-broken/29519

Steps to Reproduce

See thread. When Tasks plugin is disabled checklist items render correctly.

Context (Environment)

• Obsidian version: 0.13.14
• Tasks version: 1.4.1
• [ ] I have tried it with all other plugins disabled and the error still occurs

Possible Solution

[schemar]

As per the documentation at https://schemar.github.io/obsidian-tasks/getting-started/

Tasks only supports single-line checklist items. You cannot have checklist items that span across multiple lines.

This works:

- [ ] This is a task
    - This is a sub-item
    - Another sub-item
    - [ ] And a sub task
        - Even more details

The following does not work:

- [ ] This task starts on this line
      and then its description continues on the next line

[gwww]

I understand the caveat but thought it only applied in a Tasks view. When Tasks is enabled and not in a Task view then rendering of a checklist item with a newline no longer works. Is that limitation what is expected by the warning message?

[schemar]

Ah, sorry. I misunderstood. Normal checklist items should of course not be affected. However, it depends on your settings of the Tasks plugin. If you don't use a "Global task filter", then every checklist item is a "task". In that case, you can no longer have multi-line checklist items, as you cannot have multi-line tasks. How did you configure Tasks?

I cannot reproduce it with a "Global task filter set" and using a checklist item which doesn't include the global filter.

[gwww]

I understand now. My misunderstanding then. I did not expect a document that gets scanned for tasks in the document to alter the behaviour of how those items display. I'm not sure if I'm clear on the language here... Generated lists I understand fall under the no multi-line rule. Non-generated lists (i.e.: checklist items I type in AND those items get scanned into a task list) also fall under the no multi-line rule – which I did not expect.

Maybe a line in the document of the feature would help?

[schemar]

Definitely. Thanks for the feedback! Do you think you have the time to update the documentation? :blush: The current warning lives here: https://github.com/schemar/obsidian-tasks/blob/main/docs/getting-started/index.md?plain=1#L51

[zachdaniel]

Is there not a potential way to make this work? For example, expecting an indentation line up to match, or even some sentinal value like

- [ ] TASK>>>
Multi
Line
Task
<<<TASK

I can see why it can't work that way by default because the last task in a task list would naturally include the rest of the document. But it would be nice if there was a (potentially toggleable) way to achieve multiline task bodies, even if it required manually doing so :)

[schemar]

@gwww I never saw that you made changes. I now created a PR form your repo to mine to merge your changes.

[schemar]

@zachdaniel technically, everything is possible. It's just too time consuming on implementation and maintenance for me to do at the moment.

[zachdaniel]

Makes sense! I wonder if there was a way to offload that to the user? Like make a configurable "task regex" or something? And then if that's wrong then it's on the user to deal with.

[schemar]

I'm hesitant to give the user a foot gun. Though, who am I to withhold it. I am only worried about lots of "bug" reports due to malformed regexes :monocle_face: I'll think about it.

[dylannorthrup]

I'm hesitant to give the user a foot gun. Though, who am I to withhold it. I am only worried about lots of "bug" reports due to malformed regexes 🧐 I'll think about it.

As a user who found this issue when trying to figure out why my multi-line task wasn't getting rendered, I would endorse providing said "foot gun" behind an appropriately worded toggle/setting marked experimental and/or has a warning saying "I know this allows me to shoot myself in the foot, but I'm a rebel!" ... or some such.

Then again, I'm a long-time perl/ruby/awk/sed user and am very comfortable with regexps and HERE docs, so I will confess I'm not the typical user.

[claremacrae]

I’ve taken over stewardship of Tasks from @schemar.

I do agree that Tasks swallowing text when rendering the markdown in Reading mode is a serious limitation which needs to be fixed. It is also highly non-trivial to fix it in the current code base.

If datacore turns out to be as effective as I hope, there may be a small chance that it could be adopted and enable a fix of the rendering.

This issue is about documenting the issue, however, and the limitation is already documented, so I will later close this issue.

But having said that, the time required every day to do user support for Tasks now is already a problem, as its use has grown.

So for the avoidance of doubt, I would not support any changes that would in any way be described as a foot gun.

[claremacrae]

The documentation for this limitation is at:

https://obsidian-tasks-group.github.io/obsidian-tasks/getting-started/#limitations-and-warnings