Manual reorganisation: I don't like that emil no longer follows straight
after the section on on TI. It is a TI technique, and uses a lot of
concepts and settings (generalised force, softcoring, ifsc, clambda) from
the main TI section, so if users are reading the manual the way it is now,
they will have to remember to keep one finger shoved in the TI section as a
bookmark while they are reading about EMIL. Not critical, but a small way
to enhance the ease of reading.
Josh
On 30 January 2014 14:44, David A Case <case.biomaps.rutgers.edu> wrote:
> 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
>
_______________________________________________
AMBER-Developers mailing list
AMBER-Developers.ambermd.org
http://lists.ambermd.org/mailman/listinfo/amber-developers
Received on Wed Mar 05 2014 - 02:30:03 PST
