cmake: rewrite help2t2t into a cmake script or direct bump of manpage

[GoogleCodeExporter]

help2t2t forces us to have bash as a dependency, most of the stuff could be 
done in cmake using string(regex replace ...) and so on.

Original issue reported on code.google.com by christop...@gmail.com on 16 May 2011 at 9:38

[GoogleCodeExporter]

cmake support all needed regex - the cmake book is waiting for Konstantin in my 
office 

Original comment by christop...@gmail.com on 5 Jul 2011 at 4:19

[GoogleCodeExporter]

d.mudda is waiting in your offce

Original comment by konstantin.koschke on 5 Jul 2011 at 4:21

• Changed state: Accepted

[GoogleCodeExporter]

Update: cmake book is on your desk!

Original comment by christop...@gmail.com on 5 Jul 2011 at 4:31

[GoogleCodeExporter]

This error would also be fixed with the rewrite:
> make[2]: *** No rule to make target `help2t2t', needed by
> `scripts/help2t2t'.  Stop.
> make[1]: *** [scripts/CMakeFiles/csg_call_manpage.dir/all] Error 2
> make: *** [all] Error 2

-> High priority!

Original comment by christop...@gmail.com on 8 Nov 2011 at 5:02

• Added labels: Priority-High
• Removed labels: Priority-Low

[GoogleCodeExporter]

I came across the same issue on OpenSUSE again! So basically to build manpages, 
which a requirement for most distributions, we rely on cmake>=2.8.3 or some 
very high version of cmake 2.6.X.

All in all, I think the best would be if we could dump a manpage from the 
application itself, something like: votca_property --man

We would also get rite of the txt2tags dependency. 

Original comment by christop...@gmail.com on 1 Nov 2013 at 2:51

• Changed title: cmake: rewrite help2t2t into a cmake script or direct bump of manpage
• Removed labels: Component-Csg

[GoogleCodeExporter]

What is the format of manpage files?

In CTP latex, xml, and txt output is generated by the class 
propertyiomanipulator (we use this for calculators).
All our XML files in share have the following format
<options>
<calcname help="" default="" unit="" section="">
</calcname>
</options>

i.e.:
<options>
<idft help="Projection method for electronic couplings. Requires edft 
otput" section="sec:dft">
         <job_file help="Job control file (full path)"></job_file>
         <tasks help="What to do" 
default="input,run,parse,trim,project">input,run,parse,trim,project</tasks>
         <store help="What to store" 
default="orbitals,overlap,integrals">orbitals,overlap,integrals</store>
         <package help="XML file with options for the QM package"></package>
         <degeneracy help="Criterium for the degeneracy of two levels" 
unit="eV" default="0">0</degeneracy>
         <levels help="Output between HOMO, ..., HOMO-levels; LUMO, ..., 
LUMO+levels" default="3">3</levels>
         <trim help="Use trim*occupied of virtual orbitals" 
default="2">2</trim>
</idft>
</options>

from this we generate the tex manual, help output, xml output, etc.

Same can be done for executables. The easiest is to have an xml file 
with their documentation. It's been on the agenda for a while, but I 
haven't come up with a good solutuion how to do this. Any ideas? Victor?

Denis

Original comment by andrienko@googlemail.com on 1 Nov 2013 at 6:48

[GoogleCodeExporter]

> What is the format of manpage files?
<http://liw.fi/manpages/>

Original comment by christop...@gmail.com on 1 Nov 2013 at 7:43

[GoogleCodeExporter]

try 

votca_property --man > votca_property.1
man ./votca_property.1

if this is what is finally needed, i will add it to the Application (assuming 
that all executables are derived from it). 

Original comment by andrienko@googlemail.com on 2 Nov 2013 at 8:34

[GoogleCodeExporter]

Looks great, that was exactly what was needed. Please add that to application 
class. After that I can change cmake to generate for all apps automatically.

We should add two more sections at the end:

AUTHORS
       Written and maintained by the VOTCA Development Team <devs@votca.org>

COPYRIGHT
  <the common Apache 2.0 header>

Original comment by christop...@gmail.com on 2 Nov 2013 at 9:11

[GoogleCodeExporter]

And can we make the option hidden?

Original comment by christop...@gmail.com on 2 Nov 2013 at 9:21

[GoogleCodeExporter]

Making options was a bit of a pain, but should work. Now if you add an option 
as "Hidden", i.e.
AddProgramOptions("Hidden")("man", "  output manual pages");
it will be filtered out from the user output. Left it in the man pages for fun. 
Can be also removed from there (will be totally non-existing then).

Some programs are not derived from Application or CSGApplication. (in CTP 
everything so far is from CTPApplication unless it is a script). These programa 
will not have --man option (or it has to be added manually. Fix or complain ;)

Two remarks: I removed sections (man pages are not that long) as well as did 
not figure out where the VersionString() comes from, so no version is displayed 
at the moment, though I am using VersionString() to print it. Have no time to 
look deeper. Any ideas? Victor?

Original comment by andrienko@googlemail.com on 3 Nov 2013 at 6:46

• Changed state: Fixed

[GoogleCodeExporter]

I changed cmake of votca tools to make use of this great feature. There is also 
a votca-tools manpage, which hasn't been changed in 2 years, so I just added 
the txt2tags generated version of it to the repository. We can either edit by 
hand or generate the manpage from the t2t file whenever we change the t2t file.

For the scripts in csg, I have to think about it again, but most likely I will 
add an --man option to print a modified version of the help for the 3 script, 
which get installed in bin. The --tex option will be useful for program 
reference section of the csg manual. Changing the scripts reference section 
might be bit more complicated as we also parse the scripts for the used 
options, but that could maybe be done inside csg_call, too.

Original comment by christop...@gmail.com on 4 Nov 2013 at 5:58

• Changed state: Started

[GoogleCodeExporter]

I have also added --tex option. The format is the one we are using in ctp, but 
I think it will also be Ok for csg:

\subsection{votca\_property}
\label{prog:votca_property}
Helper for parsing XML files
\begin{compactitem}
\item[ ] \texttt{{-}h [ {-}{-}help ] }   display this help and exit
\end{compactitem}

It would be nice to use the Application object in scripts, so that one does not 
have to change formatting in two places. Python binding would be an option. Any 
other ideas?

Denis

Original comment by andrienko@googlemail.com on 4 Nov 2013 at 12:05

[GoogleCodeExporter]

I saw the --tex option, that is pretty nice, too. To fully replace txt2tags 
html output is still missing, which gets uploaded to www.votca.org inside the 
manual build (make upload), I don't think this needs to be changed right now. 
(And this could also be done with latex2html anyhow.)

Concerning the scripts, python binding might be one solution, but it will work 
with python only. How about making votca_property read the help in text or xml 
format from another program and translate it into man/tex, something like:
./script --help | votca_property --in --man
That will also work for fortran, perl, shell. All scripts in csg already have a 
help message looking just like the one of votca_property.

Original comment by christop...@gmail.com on 4 Nov 2013 at 4:35

[GoogleCodeExporter]

Original comment by christop...@gmail.com on 1 Jul 2015 at 11:40

• Added labels: Milestone-Release1.4
• Removed labels: Milestone-Release1.3