Skip to content

GitLab

  • Projects
  • Groups
  • Snippets
  • Help
    • Loading...
  • Help
    • Help
    • Support
    • Community forum
    • Submit feedback
  • Sign in
S src
  • Project overview
    • Project overview
    • Details
    • Activity
    • Releases
  • Repository
    • Repository
    • Files
    • Commits
    • Branches
    • Tags
    • Contributors
    • Graph
    • Compare
    • Locked Files
  • Issues 61
    • Issues 61
    • List
    • Boards
    • Labels
    • Service Desk
    • Milestones
    • Iterations
  • Merge requests 3
    • Merge requests 3
  • CI/CD
    • CI/CD
    • Pipelines
    • Jobs
    • Schedules
  • Operations
    • Operations
    • Incidents
    • Environments
  • Analytics
    • Analytics
    • CI/CD
    • Code Review
    • Issue
    • Repository
    • Value Stream
  • Wiki
    • Wiki
  • Snippets
    • Snippets
  • Members
    • Members
  • Activity
  • Graph
  • Create a new issue
  • Jobs
  • Commits
  • Issue Boards
Collapse sidebar
  • OPAL
  • src
  • Issues
  • #61

Closed
Open
Created Mar 16, 2017 by snuverink_j@snuverink_jDeveloper

Investigation into new manual format

Andreas and I had a discussion and mail exchange about the manual format. As a background, in my previous job I worked on a project where we converted our LaTeX manual (http://www.pp.rhul.ac.uk/bdsim/manual/). Posting some of the findings here for discussion.

Since the OPAL manual is quite extensive it will be quite some work to do it all by hand, so I did a search for a LaTeX conversion tool. Since LaTeX can define macros and there are many possible packages this is definitely not an easy conversion, there are only few options. I think our best bet is pandoc (pandoc.org).

I gave it a try on an individual chapter with many equations converting it to markdown (opalt.md). However, the current PSI gitlab wiki does not seem to support LaTeX. The latest versions do support a fairly large subset (called KaTeX) though: https://gitlab.com/gitlab-org/gitlab-ce/blob/master/doc/user/markdown.md#math and https://github.com/Khan/KaTeX/wiki/Function-Support-in-KaTeX. Andreas has contacted the PSI gitlab contact person.

I also converted to ReStructured Text (opalt.rst), which can do maths and is used for the Python documentation online (sphinx-doc.org), and then to plain html without a fancy theme that can be easily added (opalt_rst.html). It doesn't run particularly well with quite a few warnings.. Still it did some equations correctly, so not hopeless either.

Then I fixed the simple error messages in around 5-10 minutes and the result is also attached (opalt_mod.rst and opalt_rst_mod.html). Figures are still missing (pdfs are not liked in html very much, so probably need to be converted) and some LaTeX macros are not seen (since I disabled header.tex and footer.tex), but these are issues that can be fixed.

I think this gives a sort of idea of what it could become and the work that is needed (I reckon 10-20 hours).

Assignee
Assign to
None
Milestone
None
Assign milestone
Time tracking