Project

General

Profile

Bug #690

options program needs to be built by default

Added by Mark Abraham almost 10 years ago. Updated almost 8 years ago.

Status:
Closed
Priority:
Low
Assignee:
Category:
analysis tools
Target version:
Affected version - extra info:
Affected version:
Difficulty:
uncategorized
Close

Description

In 7724b23bb I moved options.c from src/contrib (where CMake ignored it) to src/tools so the manual can be built in an up-to-date way.

Subsequent discussion with Christoph Junghans suggested the options program needs to have a more regular existence.

So I'll make it into g_options, adapt build machinery accordingly, and alert Teemu so it doesn't get lost in the tools re-shuffle.


Related issues

Related to GROMACS - Task #666: Improve help printing in the command-line runnerClosed01/14/2011
Related to GROMACS - Feature #969: Generating man pages, html help etc. from OptionsClosed07/12/2012

Associated revisions

Revision 8c4c1600 (diff)
Added by Mark Abraham almost 10 years ago

Renamed src/tools/options.c

IssueID #690

Revision 56b72ffe (diff)
Added by Mark Abraham almost 10 years ago

Turned g_options into a normal GROMACS tool

Made the old src/contrib/options into g_options which is built and
installed by CMake by default.

IssueID #690

Revision 93680f44 (diff)
Added by Mark Abraham almost 10 years ago

Added forgotten file

IssueID #690

Revision 5524a41d (diff)
Added by Mark Abraham almost 10 years ago

Updates to manual to reflect new g_options status

IssueID #690

Revision 24e0a341
Added by Roland Schulz over 9 years ago

Merge remote branch 'origin/release-4-5-patches'

Conflicts:
src/tools/CMakeLists.txt
src/tools/Makefile.am
src/tools/gmx_membed.c
src/tools/gmx_saltbr.c

Conflict of adding g_options: Undid adding of g_options to src/tools/CMakeLists.txt
IssueID #690

History

#1 Updated by Roland Schulz over 9 years ago

Christoph had earlier in the master branch solved this problem by adding g_options within the contrib folder to Cmake.
commits: 563999240cf57317087c80393c617925311dc63a and d76b784064acdd6866d31bf74eb9f8533fd0ee55

Which approach is better? I assume the same should be used for master and release. This problem came up when I tried to merge.

I went ahead and used Mark's approach because it is the newer and Mark writes he talked to Christoph. The merge is 24e0a341512eff8984c1541140e01e9d52bb6fa5. Please let me know if that is not correct.

#2 Updated by Teemu Murtola over 9 years ago

Is there some specific use case that requires the g_options program to be installed? That is, what's the benefit for an end user? In the long rung, I think it would be better to be able to build the manual without installing anything, and just have the build system for the manual take a path to a build tree as an input.

#3 Updated by Mark Abraham over 9 years ago

I didn't explore the reason Christoph had for wanting g_options to be an installed program. I don't really care what the final resolution is, so long as it's easy to get a current version of the program for building the manual.

#4 Updated by Justin Lemkul over 9 years ago

It seems that the options program is somewhat superfluous. Its purpose is to write a simple .html and .tex file (and contains only text anyway, no real code of any consequence), although it appears no one has bothered to write the .html file since version 2.0 - yikes!

http://manual.gromacs.org/current/online/options.html

An "options.tex" file could easily be added to the manual source files and simply maintained there, although automatic generation of an .html file needs a solution. It seems that doing so has been a (very) low priority.

#5 Updated by Christoph Junghans over 9 years ago

@Teemu: In gentoo g_options is used to build a live version of the gromacs manual. However, I think it would be completely ok to have extra rules, like make g_options and make install-g_options to build and install it and not to install it by default. And g_options is only important to have in the master branch. For the stable (released) version there is a manual on the website.

@Roland: I prefer the solution of Mark, it is much cleaner. Btw. thanks for merging it. However if we get feature #685 done, the whole issue of installing or not-installing is sovled anyway.

@Justin: I was always wondering why gromacs has its own "markup language", but I guess this has more historical reasons. Nowadays there are several programs around doing a better job. In our Votca package we are using txt2tags, because it is one python script and very easy to extend with special rules.

#6 Updated by Teemu Murtola over 9 years ago

Christoph Junghans wrote:

@Teemu: In gentoo g_options is used to build a live version of the gromacs manual. However, I think it would be completely ok to have extra rules, like make g_options and make install-g_options to build and install it and not to install it by default. And g_options is only important to have in the master branch. For the stable (released) version there is a manual on the website.

In this scenario, is there need to build the manual completely independently of building Gromacs? If both are built at the same time, there should be no need to install g_options, but just run it from the build tree. Of course, the current build system for the manual may not allow this, but that could be fixed. But I agree that if/when #685 gets implemented, the same functionality can just be included in the wrapper binary.

@Justin: I was always wondering why gromacs has its own "markup language", but I guess this has more historical reasons. Nowadays there are several programs around doing a better job. In our Votca package we are using txt2tags, because it is one python script and very easy to extend with special rules.

I guess as well that the reasons are mainly historical; 10-15 years ago there might not have been as many ready-made solutions as there are now. :) But besides the markup, I think the main idea in Gromacs is that the documentation is only in one place, so that it does not get as easily out of sync. If the tools should support on-line help as they do now, and one also wants the manual in other formats, it at least doubles the maintenance effort if they are not all generated from the same source. And it probably takes some serious thinking and programming to get a robust system of generating on-line help into the tools from external files. But it would still be one option to think about; as such, this issue also relates to #666, and should perhaps be thought about before substantial effort is put into that one. With the new analysis framework, there will also be much more documentation that is common to all analysis tools.

#7 Updated by Christoph Junghans over 9 years ago

Teemu Murtola wrote:

@Justin: I was always wondering why gromacs has its own "markup language", but I guess this has more historical reasons. Nowadays there are several programs around doing a better job. In our Votca package we are using txt2tags, because it is one python script and very easy to extend with special rules.

I guess as well that the reasons are mainly historical; 10-15 years ago there might not have been as many ready-made solutions as there are now. :) But besides the markup, I think the main idea in Gromacs is that the documentation is only in one place, so that it does not get as easily out of sync. If the tools should support on-line help as they do now, and one also wants the manual in other formats, it at least doubles the maintenance effort if they are not all generated from the same source. And it probably takes some serious thinking and programming to get a robust system of generating on-line help into the tools from external files. But it would still be one option to think about; as such, this issue also relates to #666, and should perhaps be thought about before substantial effort is put into that one. With the new analysis framework, there will also be much more documentation that is common to all analysis tools.

My point was more that it would be nice to add txt2tags syntax support to the gromacs tools and one would have all txt2tags targets (man, *wiki, html, ...) for free.

#8 Updated by Teemu Murtola over 9 years ago

Christoph Junghans wrote:

My point was more that it would be nice to add txt2tags syntax support to the gromacs tools and one would have all txt2tags targets (man, *wiki, html, ...) for free.

That still requires either 1) writing a custom parser for the syntax to produce the on-line help, 2) writing a converter from the current markup syntax to the new syntax, or 3) invoking an external program to produce the on-line help. But I agree, it would be a good idea to use some single intermediate format for output from the Gromacs programs, and then use an external tool to convert that output to different formats. Whether that intermediate format is txt2tags, asciidoc, or something else, is up to discussion. It should certainly be thought about for issue #666.

Of the options mentioned above, 3) is not very attractive because of the runtime dependencies it creates. I would prefer option 1), although it would perhaps mean a bit more work initially.

#9 Updated by Christoph Junghans over 9 years ago

Teemu Murtola wrote:

Of the options mentioned above, 3) is not very attractive because of the runtime dependencies it creates. I would prefer option 1), although it would perhaps mean a bit more work initially.

Well for txt2tags the dependency would be a single python script, namely txt2tags itself. (That is the 1st reason why we choose it in votca, the 2nd is that it is GPL-2 and the 3rd it exists already around for 9 years.) Of course one indirectly gets python as a dependency, but on machines, where there is no python, one will most likely not build the documentation ;-)

#10 Updated by Teemu Murtola over 9 years ago

Christoph Junghans wrote:

Well for txt2tags the dependency would be a single python script, namely txt2tags itself. (That is the 1st reason why we choose it in votca, the 2nd is that it is GPL-2 and the 3rd it exists already around for 9 years.) Of course one indirectly gets python as a dependency, but on machines, where there is no python, one will most likely not build the documentation ;-)

I agree that for building the documentation, Python is a reasonable dependency, and I don't see that as a problem. But requiring Python for getting sensible output for, e.g., mdrun -h, could be problematic. This would be the option 3) in my previous comment.

Just for clarification: in all my comments above, when I've been referring to "online help", I've meant the help produced by, e.g., mdrun -h. If we want to keep that (and I don't see a reason why not), and produce that from the same source as the other forms of help (manual, HTML, ...), I don't see any other options than the three I mentioned above. Or perhaps a fourth one, where (part of) the help text would be maintained externally, and, e.g., txt2tags would be used to generate code that's compiled into the binary (or an external data file that is read in), and produces the plain text help. But this would easily get quite complex if/when we still want to produce the help for the command-line arguments directly from the definitions in the source code.

#11 Updated by Rossen Apostolov over 9 years ago

  • Affected version - extra info set to current git master

#12 Updated by Teemu Murtola almost 8 years ago

  • Status changed from In Progress to Closed
  • Target version set to 4.5.6
  • Affected version - extra info deleted (current git master)

Don't see any reason to keep this issue open. Set target version to 4.5.6, although this has been fixed already in 4.5.4. Any discussion here relevant for #969 can be found through the related issue link.

Also available in: Atom PDF