search

commonmark / cmark

CommonMark parsing and rendering library and program in C
Other
1.6k stars 535 forks source link

LaTeX output: more complete version #98

Closed gromain closed 8 years ago

gromain commented 8 years ago

I was wondering if the LaTeX output should include the necessary header for the file to compile directly with LaTeX interpretor. Right now, there is now \begindocument and more importantly, the necessary \includepackage are not documented anywhere. I think cmark LaTeX output would benefit from either of the two solutions:

Or both!

Is there anyone working on the subject? Maybe I can try to tacle it!

Thoughts?

jgm commented 8 years ago

The LaTeX output is like the HTML and man output -- it's a document fragment, which needs the necessary header and footer. This could be stated more clearly in the README. I wouldn't want to change the behavior, since it's often very useful to generate a fragment, and people's needs with document headers tend to vary quite a bit.

It would also be helpful to document which LaTeX packages are required. If you want to suggest some revisions to the README, please feel free.

You might also check out my project jgm/lcmark, which uses libcmark but adds templates, YAML metadata, and filters written in lua.

+++ Romain Bazile [Jan 18 16 05:22 ]:

I was wondering if the LaTeX output should include the necessary header for the file to compile directly with LaTeX interpretor Right now, there is now \begindocument and more importantly, the necessary \includepackage are not documented anywhere I think cmark LaTeX output would benefit from either of the two solutions: * Better documentation around what's included in the ouput and what is not * Including the actual needed part in the output

Or both!

Is there anyone working on the subject? Maybe I can try to tacle it!

Thoughts?

— Reply to this email directly or [1]view it on GitHub.

References

  1. https://github.com/jgm/cmark/issues/98
gromain commented 8 years ago

I do agree this is probably better than trying to find a one size fits all thing that probably won't work. I'll fork your repo and send a pull request with an updated README that makes it clearer! What do you think (apart from what we just discussed) could be improved regarding the README or the documentation overall? Are there any elements missing you think could be added or any part where I could put my eyes on and try and improve them?

jgm commented 8 years ago

+++ Romain Bazile [Jan 18 16 09:31 ]:

I do agree this is probably better than trying to find a one size fits all thing that probably won't work. I'll fork your repo and send a pull request with an updated README that makes it clearer! What do you think (apart from what we just discussed) could be improved regarding the README or the documentation overall? Are there any elements missing you think could be added or any part where I could put my eyes on and try and improve them?

Nothing else I can think of. Note that the main documentation for the command line program and lib is in the man pages: man/man1/cmark.1 and man/man3/cmark.3.

gromain commented 8 years ago

So maybe I should include modifications to those too, to be consistent and complete?

jgm commented 8 years ago

Yes, it may be that some of these things belong in the man pages rather than the README.md (or in addition -- though I'd like to avoid having the same content in multiple places).

Note that the cmark.3 man page is generated automatically from comments in cmark.h, so you shouldn't modify it manually in the repository.