He everyone:
Below are some slightly edited comments from Romain about the manual
reorganization; I agree with almost all of this.
Right now, *you* can help by (a) adding more cross-references and examples;
(b) critically reading sections you didn't write, clarifying things that
aren't as clear as they should be (or posting problems to the developers'
list).
...thx...dac
----- Forwarded message from "Romain M. Wolf" <romain.wolf.gmail.com> -----
From: Romain M. Wolf <romain.wolf.gmail.com>
Subject: some thoughts about TeX and HTML Amber manuals
Date: Tue, 28 Jan 2014 20:22:13 +0700
(b) I have not yet encountered any tool that can convert TeX to HTML
without flaws (and I have tried a few). Any generated HTML requires
further editing. Math and figures are usually not converted as expected
(if at all). This can be very time-consuming.
(c) I think that sticking to LaTeX (or LyX, if that is the favoured
interface of the Amber community) and then generating PDF with lots of
cross references remains the best choice.
(d) A complete reorganisation of the Amber documentation would be a
good thing, although it might take more effort than anticipated. Simple
rearranging the various current chapters might not be enough.
Some ideas (from the viewpoint of a user, not a developer) follow
below. Combining the Amber and AmberTools documentation is a must in my
opinion. But nobody new to Amber (or even with some knowledge) will read
the documentation like a novel. Cross-references are essential. Therefore,
a new PDF (and/or HTML) documentation would require more cross-references
than currently available. Also, all specific chapters should be read and
reviewed by people who have never (or rarely) used the specific technique
to ensure that the documentation is understandable by non-specialists
(and not just the key developer). Although I have used Amber-related
stuff for a number of years now, I often run into problems to understand
consequences of changes to the default settings in numerous cases
(especially in sander and pmemd, sometimes in NAB also). Especially
combinations of settings that do not make sense are a problem. Many
of these are captured, but my feeling is that there are still various
senseless setting combinations that escape the automatic check.
A possible reorganisation of the manual could be:
(1) general (although more detailed than currently) description of typical
work flow preparation of files (more important than acknowledged by
most developers, it seems to me) choice of force field(s) choice of
methods (goal of simulation, what results to expect, CPU expenses (GPU,
MPI), pitfalls) execution of simulation (most common settings, with
cross-references to the detailed descriptions) analysis (short description
of options and tools, again with cross-references to the details)
(2) description of force fields parameters, differences between
force fields, best choice for planned simulation parameters and
parameter-topology file details,
(3) the various detailed chapters (in any order to be chosen)
LeaP (tleap, xleap, others)
sander
pmemd
NAB
3D-RISM
GB and PB variants
various small but useful tools
maybe a chapter highlighting the differences between sander, pmemd, and
NAB variants for doing similar stuff
(4) analysis
cpptraj
mm(pb/gb)sa
others
(5) tutorials (more or less detailed, with cross-references to the various
chapters) more annotated examples of control files than currently in the
documentation various default settings and consequences of overwriting
them
This is a very general outline. I believe the whole rewrite would require
more time than available until the next release. But the revised doc could
also follow independently of the actual software release, maybe at a
midterm.
I would be willing to participate in that effort, if my time permits
(i.e., mostly in my free time, on rainy weekends or sleepless nights, or
sitting around in Thailand on tropical evenings, like just now).
---regards---romain
Romain M. Wolf
romain.wolf.gmail.com
----- End forwarded message -----
_______________________________________________
AMBER-Developers mailing list
AMBER-Developers.ambermd.org
http://lists.ambermd.org/mailman/listinfo/amber-developers
Received on Thu Jan 30 2014 - 06:00:04 PST
