search

HSF / documents

Repository for HSF documents (e.g. technical notes)
6 stars 29 forks source link

Technical note on software lacks LaTeX source #149

Open graeme-a-stewart opened 10 months ago

graeme-a-stewart commented 10 months ago

The published version of the technical note on software project best practices is evidently generated from a LaTeX version of the document. However, all that is in GitHub is the original Markdown.

Can either of @hegner or @drbenmorgan remember how we did this change or where the LaTeX is?

I would propose that after accepting the recent change in #148 we just convert the master document to LaTeX (with pandoc) and consider the MD obsolete.

What do you think?

hegner commented 10 months ago

Thanks Graeme! I approved your change. The diff'ing of Github was a bit confused by the newlines and reformatting. I hope I caught all your changes. Why cannot we keep the current document and explain which pandoc command to use?

graeme-a-stewart commented 10 months ago

The problem is that pandoc provides an incomplete LaTeX file (the first line is \section). It's like a snippet that you need to then insert into another LaTeX file. That seems like quite a faff, so instead of maintaining two files (the boilerplate and the markdown), it looked easier to just bite the bullet and say we have a LaTeX document as the master.

hegner commented 10 months ago

I see. Does this help? https://github.com/HSF/documents/blob/master/HSF-TN/templates/pandoc_example.md

Maybe I should make that more explicit in the README