Markdown processing does not allow/support non-documentation sections

[rhdunn]

Using cldoc 1.6, having a markdown file with:

# License
Description of the license for the file.
#<cldoc:test>
Test documentation.

Causes a "Failed to merge file... no #cldoc:id specified" error.

Doing the reverse:

#<cldoc:test>
Test documentation.
# License
Description of the license for the file.

Causes test to have a <doc>#License Description of the license for the file.</doc> node associated with it.

Doing:

#<cldoc:test>
Test documentation.

@return Some value.
# License
Description of the license for the file.

does not cause the License section to be added to the documentation.

In all these cases, the additional header contents should be ignored as in markdown this should create a new section.

[jessevdk]

I'm not sure I understand. A new section of what? cldoc does not support markdown titles as special segments, they are just going to be part of the documenting element. If you want to make special documentation pages, use categories. Am I misunderstanding something?

[rhdunn]

What I am trying to do here is add a license to the documentation files (Copyright line and which license (Apache, Creative Commons, etc.) the documentation is licensed under). I tried this above, e.g.:

Copyright (C) ...

This file is licensed under the Creative Commons Attribution (CC-BY) 2.0 license.

#<cldoc:id>

Brief description.

However, cldoc did not like that (it complained it could not find a #<cldoc:id>). Therefore, I added a License section at the end:

#<cldoc:id>

Brief description.

# License

This file is licensed under the Creative Commons Attribution (CC-BY) 2.0 license.

Copyright (C) ...

[jessevdk]

Ideally, there would be support for some commented sections in markdown. The only thing that I found that people tend to do, is to use xml/html style comments (i.e. ), which will still end up in the output, but are obviously then not rendered. Would this be an acceptable solution for you?

[rhdunn]

I would prefer it if there were a more markdown friendly approach (hence the use of sections).

Another approach I could do is use a YAML front section like is done for jekyll-based markdown files, where I do, e.g.:

---
_copyright_: "Copyright ..."
_license_: "CC-BY-SA 3.0"
---

If you do not want to make cldoc support this, I can run the markdown through a filter that will remove the YAML front section before it gets passed to cldoc.

[jessevdk]

I don't want to hijack markdown semantics for special purposes. This also seems like quite a specific use case, so I'm not really willing to introduce yaml into the markdown file just for this. If you want to go the filter way, you can use --merge-filter.

[rhdunn]

Fair enough.