[Rivet] Rivet metadata proposal

[Andy Buckley]

Hi all,

As promised, I've got a proposal for new metadata methods to be added to
Rivet. These will be used to build the manual and web pages, as well as
the command line analysis querying. Please have a look at the list of
proposed method signatures below (to be made public in the Analysis base
class) and let me know if you think they are adequate, or if you have
any suggestions/extra requests.

Note that the description() method has been renamed summary(), to leave
description() free to be used for a longer description (in LaTeX
format.) When we've decided on a final metadata API (in the next couple
of days, I hope), I will do this aspect of the migration myself to
alleviate confusion.

Here's my proposal:


Analysis.hh:

 /// @name Metadata
 /// Metadata is used for querying from the command line and also for
 /// building web pages and the analysis pages in the Rivet manual.
 //@{
 /// Get the name of the analysis. By default this is computed by
 /// combining the results of the experiment, year and Spires ID
 /// metadata methods and you should only override it if there's a
 /// good reason why those won't work.
 virtual std::string name() const {
   return experiment() + "_" + year() + "_S" + spiresId();
 }

 /// Get a description of the analysis.
 virtual std::string spiresId() const = 0;

 /// @brief Names & emails of paper/analysis authors.
 /// Names and email of authors in 'NAME <EMAIL>' format. The first
 /// name in the list should be the primary contact person.
 virtual std::vector<std::string> authors() const = 0;

 /// @brief Get a short description of the analysis.
 /// Short (one sentence) description used as an index entry.
 /// Use @a description() to provide full descriptive paragraphs
 /// of analysis details.
 virtual std::string summary() const = 0;

 /// @brief Get a full description of the analysis.
 /// Full textual description of this analysis, what it is useful for,
 /// what experimental techniques are applied, etc. Should be treated
 /// as a chunk of LaTeX text, including equations built with amsmath
 /// operators, and splitting paragraphs with newlines as usual. The
 /// TeX will be down-rendered to text or HTML as necessary.
 virtual std::string description() const = 0;

 /// @brief Information about the events needed as input for this analysis.
 /// Event types, energies, kinematic cuts, particles to be considered
 /// stable, etc. etc.
 virtual std::string runInfo() const = 0;

 /// Experiment which performed and published this analysis.
 virtual std::string experiment() const = 0;

 /// @brief When the original experimental analysis was published.
 /// When the refereed paper on which this is based was published,
 /// according to SPIRES.
 virtual std::string year() const = 0;

 /// Journal, and preprint references.
 virtual std::vector<std::string> references() const = 0;

 /// Whether this analysis is trusted (in any way!)
 virtual std::string status() const {
   return "UNVALIDATED";
 }
 //@}


-- 
Dr Andy Buckley
Institute for Particle Physics Phenomenology
Durham University
0191 3343798 | 0191 3732613 | www.insectnation.org