Pull everything we can out of CasterQuickReference.tex and add content to ReadTheDocs

[kendonB]

LaTeX is hard for newbies to use. LaTeX is hard for people who have used it for years to use (i.e me).

I propose that we pull a lot of the stuff in CQR out and put it into readthedocs.

The big drawback which would prevent us from doing this for everything is that markdown doesn't do footnotes. However, a lot of the current CQR doesn't have footnotes. I don't think being able to nicely print docs on paper is that big a deal now that people can say "bring me X doc page".

It is also possible to hack table footnotes in markdown using superscripts which may also be an option.

---

Want to back this issue? Post a bounty on it! We accept bounties via Bountysource.

[LexiconCode]

I'm in agreement here. As is much as I love the pretty formatting and print ability on paper LaTeX is difficult to maintain. This issue is worse for beginners and I reached my limits with aspects of it as well.

Doing a bit of research after we talked last night.

You can use Markdown and reStructuredText in the same Sphinx project.

Install recommonmark (pip install recommonmark) and then edit conf.py:

from recommonmark.parser import CommonMarkParser

source_parsers = {
    '.md': CommonMarkParser,
}

source_suffix = ['.rst', '.md']

Which opens up the door for advanced formatting. This cheat sheet while a bit old seems very sustained.

[comodoro]

I don't have preference here, but I don't think maintainability is an issue. Only very few commands are in the CQR, and Overleaf can be used for compilation.

[sovoid]

Hi folks I'm new to Caster but love the ecosystem. I have used Python in the past but not that extensively. I'd love to work on this issue since this involves much of the docs to get me started. Any pointers would be awesome. Thank you

[LexiconCode]

Hi folks I'm new to Caster but love the ecosystem. I have used Python in the past but not that extensively. I'd love to work on this issue since this involves much of the docs to get me started. Any pointers would be awesome. Thank you

Welcome! A few thoughts:

Use pandoc to convert CasterQuickReference.tex into Markdown or reStructuredText. I'm pretty sure reStructuredText will be a better conversion as it's much more advanced.

Use reStructuredText. You could use VS Code with the following extension vscode-restructuredtext

Use markdown is an option markdown_tables at way to organize the documentation. I'm not sure how to quite represent footers though as seen in CasterQuickReference.pdf as its syntax is quite limited.

[sovoid]

Hi folks I'm new to Caster but love the ecosystem. I have used Python in the past but not that extensively. I'd love to work on this issue since this involves much of the docs to get me started. Any pointers would be awesome. Thank you

Welcome! A few thoughts:

Use pandoc to convert CasterQuickReference.tex into Markdown or reStructuredText. I'm pretty sure reStructuredText will be a better conversion as it's much more advanced.

Use reStructuredText. You could use VS Code with the following extension vscode-restructuredtext

Use markdown is an option markdown_tables at way to organize the documentation. I'm not sure how to quite represent footers though as seen in CasterQuickReference.pdf as its syntax is quite limited.

@LexiconCode that makes sense. I havent use pandoc before but there is only one file to convert if i am not wrong for the start? I will try to set it up and update you on how it works. Do you want me to raise a draft pull request so that you can check on the progress so far?

[LexiconCode]

@LexiconCode that makes sense. I havent use pandoc before but there is only one file to convert if i am not wrong for the start? I will try to set it up and update you on how it works. Do you want me to raise a draft pull request so that you can check on the progress so far?

Yes you should be able to convert CasterQuickReference.tex as I contains everything that's generated in the PDF.
https://pandoc.org/MANUAL.html Hopefully the conversion works well.

Feel free to open up a draft PR. I'll do what to work with you.

[sovoid]

@LexiconCode just a short update on my part. I've started working on this issue today and have already setup pandoc. I'm having some trouble setting up miktex on windows so I'm going to try setting it up on WSL2. From my understanding I just have to run a pandoc command to convert .tex to a .rst file is that correct and then manually check what parts are broken?

[LexiconCode]

I'm not going to be able to take a closer look at this until the 24th. Considering the goals for whatever we use we need a format that can be diff in get and easy to use. With those goals in mind is there a way to use a word processor which everybody knows how to use and is freely available.

With pandoc we can convert word document formats to PDF pretty easily. The issue with that is there is a binary that git cant diff. However this looks like a solution to that.
https://medium.com/@mbrehin/git-advanced-diff-odt-pdf-doc-xls-ppt-25afbf4f1105

Noting this here for another avenue of pursuit. @und3fined-v01d you might experiment putting this into a Word document instead.