Project

General

Profile

Feature #179

docbooks?

Added by Tunnell, Christopher almost 11 years ago. Updated almost 10 years ago.

Status:
Closed
Priority:
Low
Assignee:
Category:
Documentation
Target version:
Start date:
06 November 2010
Due date:
% Done:

100%

Estimated time:
Workflow:

Description

http://www.docbook.org/

use for doucmnetation


Related issues

Related to MAUS - Feature #173: commonCpp/Simulation/FillMaterials jsonRejectedBayes, Ryan05 November 2010

Actions
Related to MAUS - Feature #299: ConfigurationDefaults -> wiki formatRejectedRogers, Chris28 January 2011

Actions
Related to MAUS - Feature #373: Configuration managementRejectedRogers, Chris10 March 2011

Actions
Related to MAUS - Feature #606: Automatic generation of documentation from json schemaClosedRogers, Chris02 August 2011

Actions
#1

Updated by Tunnell, Christopher almost 11 years ago

  • Priority changed from Normal to Low

I would need help with this. It'll be wiki documentation at first.

#2

Updated by Tunnell, Christopher almost 11 years ago

  • Assignee set to Tunnell, Christopher
  • Target version changed from MAUS-v0.0.1 to Future MAUS release

v 2.0 since wiki until then

#3

Updated by Rogers, Chris over 10 years ago

I couldn't figure out how to actually write docbooks stuff. Looks like it's some XML thing, but I don't know if there are (free) apps to write in docbook format. All of the parsers seem to just convert to latex anyway and then to html or whatever, but I guess docbook has some nice features? Not quite sure.

#4

Updated by Tunnell, Christopher over 10 years ago

I've never actually used it. I've heard that the Majoranna experiment uses it and likes it. It also seems that a lot of good software projects use it.

I put this to v2.0 (meaning sometime in the far future) because it would be nice to have something a little more professional than a wiki page at some point. But who knows...

You have other suggestions for non-wiki stuff? Or do you think it's good enough?

#5

Updated by Rogers, Chris over 10 years ago

Google returned a useful looking link

http://wiki.docbook.org/topic/DocBookAuthoringTools

but there seems to be some weird network problem (can see google search but not google cache, nor docbook.org?) causing weirdness.

#6

Updated by Rogers, Chris over 10 years ago

  • Assignee changed from Tunnell, Christopher to Aslaninejad, Morteza

This is a bit more relevant as tracker crew have invested some time in making a manual. Morteza, could you investigate doc books format and comment? I suspect docbooks is better than latex (docbook is some XML format), but I am not very knowledgeable. Sort of what we want for a manual is something like what GNU produce - see e.g. GNU Scientific Library documentation.

So the point is that we can make single big html document, broken hyperlinked html document, single big pdf/ps document. Also we want a base layer that is text so that we can easily log changes and it interfaces well with bzr.

Note that there is some existing documentation on the geometry and field models written in open office. You can see it at:

http://micewww.pp.rl.ac.uk/projects/maus/repository/entry/doc/run_control/Mice_Module.odt
http://micewww.pp.rl.ac.uk/projects/maus/repository/entry/doc/run_control/Mice_Module.pdf

This needs to be exported to <some text format>. It would be good if all of the documentation tied together nicely.

#7

Updated by Tunnell, Christopher over 10 years ago

I'm not convinced latex would be that bad an idea if it can spit out HTML since then people could copy-paste into and from their thesis.

I guess Morteza just decides. We need both HTML (website) and PDF (ship with code or download to laptop).

#8

Updated by Rogers, Chris over 10 years ago

So I'm looking into release for 0.0.2, and my teeth are clenching around this problem of how we handle documentation. At the moment it's a mess:

  • perl script to generate documentation from inline comments on datacards
  • materials documentation generated by hand? in 2006? and exported to wiki
  • MiceModules documentation generated by hand in open office and exported to html and pdf
  • Some user documentation generated by hand in the MAUS wiki
  • Some user documentation generated by hand in the G4MICE wiki
  • New tracker software manual
  • doxygen documentation generated by hand
Plus undocumented (but needs some documentation):
  • data structure
  • datacards replacement - "configuration" - stuff
#9

Updated by Rogers, Chris over 10 years ago

Another requirement - has to be under some version control...

#10

Updated by Tunnell, Christopher over 10 years ago

I'm worried too. I think the steps are:

1. document the first 15 minutes of MAUS usage like a tour
2. collect the mess of stuff written and triage then create links
3. docbooks or latex.

With docbooks I had trouble figuring it out honestly. I spent an hour or so and maybe was just being slow, but latex is at least a format everybody needs to know anyways. TTH looks decent at converting latex and so does hyperlatex.

#11

Updated by Tunnell, Christopher over 10 years ago

Can MOrteza confirm he sees this?

#12

Updated by Rogers, Chris about 10 years ago

I think we do latex. It goes in $MAUS_ROOT_DIR/doc/. We have a shell? script that parses it (by calling pdflatex or similar).

Latex:
  • converts to pdf
  • converts to html
  • can be modular
  • can be included in theses/technical notes/etc
  • can be generated/edited by scripts

Structure something like:

Documentation -> Tour (~ few pages) + examples
              -> Operations manual (~ few pages)
              -> Reference -> MiceModules -> geometry
                                          -> fields
                                          -> materials

                           -> configuration datacards

                           -> detectors   -> tracker
                                          -> tof
                                          -> Ckov
                                          -> EMR

                           -> data structure

                           -> analysis stuff? x-boa? optics?

Edit to add operations manual

#13

Updated by Rogers, Chris about 10 years ago

  • Assignee deleted (Aslaninejad, Morteza)
#14

Updated by Rogers, Chris about 10 years ago

  • Assignee set to Rogers, Chris
  • Target version changed from Future MAUS release to MAUS-v0.1.0
#15

Updated by Rogers, Chris about 10 years ago

Added wiki page UserDocumentation to record how we do documentation

#16

Updated by Rogers, Chris almost 10 years ago

So I added a documentation latex skeleton. Needs a sconscript. Need to convert mice modules to latex format. Need to start filling in docs...

#17

Updated by Tunnell, Christopher almost 10 years ago

Is this generally user information? Or are we wanting to use docbooks?

#18

Updated by Rogers, Chris almost 10 years ago

I don't understand the question.

This will be reference user information. Some cross-talk between the code documentation and the user documentation. But I think we need both.

Googling, docbooks looks a bit obscure/poorly documented. Latex is well known and well documented. So I don't want to do docbooks.

#19

Updated by Tunnell, Christopher almost 10 years ago

I'd just say update the title

#20

Updated by Rogers, Chris almost 10 years ago

  • Status changed from Open to Closed
  • % Done changed from 0 to 100

Added latex skeleton in doc/doc_src. Now to fill it...

#21

Updated by Rogers, Chris almost 10 years ago

  • Target version changed from MAUS-v0.1.0 to MAUS-v0.0.9

Also available in: Atom PDF