comonicon
Comonicon garbles long docstrings
I think the example below more than illustrates the issue.
"""
An example taken from `git clone --help`.
# Description
Clones a repository into a newly created directory, creates remote-tracking branches for each branch in
the cloned repository (visible using git branch --remotes), and creates and checks out an initial branch
that is forked from the cloned repository’s currently active branch.
After the clone, a plain git fetch without arguments will update all the remote-tracking branches, and a
git pull without arguments will in addition merge the remote master branch into the current master
branch, if any (this is untrue when "--single-branch" is given; see below).
This default configuration is achieved by creating references to the remote branch heads under
refs/remotes/origin and by initializing remote.origin.url and remote.origin.fetch configuration
variables.
# Examples
- Clone from upstream:
```
\$ git clone git://git.kernel.org/pub/scm/.../linux.git my-linux
\$ cd my-linux
\$ make
```
- Make a local clone that borrows from the current directory, without checking things out:
```
\$ git clone -l -s -n . ../copy
\$ cd ../copy
\$ git show-branch
```
- Clone from upstream while borrowing from an existing local directory:
```
\$ git clone --reference /git/linux.git \
git://git.kernel.org/pub/scm/.../linux.git \
my-linux
\$ cd my-linux
```
- Create a bare repository to publish your changes to the public:
```
\$ git clone --bare -l /home/proj/.git /pub/scm/proj.git
```
"""
@cast clone() = nothing
Produces
I see this is due to:
https://github.com/comonicon/Comonicon.jl/blob/ebb18333389d6cdbaae2c191315d4b8c8de5290c/src/ast/utils.jl#L32-L63
Which simply doesn't allow for meaningful newlines.
IMO the root issue here is Comonicon turning the Markdown.MD docstring into a String too early and thus loosing the ability to treat different syntactic forms differently.
I was hoping that this would just take a small tweak to the codebase, but having looked a bit more I must say I think the approach to docstrings could do with a minor overhaul. That's a larger topic though, and so I'll make a separate issue for that.
Comonicon 0.12.17/master
See my comment in #213, and yes, the main reason is I was being lazy when wrote the markdown transforms and just turn it into a String instead of keeping the AST nodes. Ideally, the long description should be stripped out in the brief and only shows in the help page of the corresponding command (not upper level)
actually I'm curious where did you see the #Description section @tecosaur I don't think this is something supported at all?
Besides passing the markdown which I don't think is necessary right now (given the stdlib Markdown does not support indented output), you can define short description as the first paragraph and long description using the #Intro section. In the future, we might want to switch to MarkdownAST package's output but its gonna depends on how much latency it brings into this package.
The only thing I think need to be done is consider passing other markdown sections to help page in some format.