Skip to content

WIP: Idea for a user reference manual

Linus Pithan requested to merge latex_based_pdf_ref_manual into master

Here is an idea for a user reference manual based on latex. I did not go far especially with the layout as I do not want to waste time in case it is decided we don't want to go this way.

The aim: To me the doc that we have with mkdocs is rather focused for developers (BCU members) and we are still missing a document for end users (esrf scientist and visiting scientist) explaining only the bliss shell, some concepts that will stumble across when using bliss and most importantly provide a reference manual.

What I did:

  • provide a simple python script to compile the latex document
  • provide commands to take context from doc strings
  • provide commands to take context from mkdocs

Why I support this solutions:

  • scientists are used to latex documents, so it is easy for them to navigate through them.
  • it natively produces a single pdf file
  • I hope to motivate scientists to contribute to the latex document
  • it is really easy to have cross-references and an index in latex

Here is what the output-pdf would look like in the moment. bliss_ref_manual.pdf

Merge request reports