All,
>> I have noticed a slightly annoying (if small) side effect of the move
>> to lua module files. Specifically, module help and whatis statements
>> will now be split up across multiple lines if they are so formatted in
>> the easyconfig. An example follows at the end of this message.
>> [...]
>>
>> This could be fixed, if desired, by removing all instances of the
>> following in descriptions:
>>
>> “””Some text
>>
>> Split up
>>
>> Into multiple lines”””
>>
>> And replacing it with:
>>
>> “Text all together on a single (probably long) line”
>>
>> Any thoughts in this regard?
>>
>>
>
> 1) if you syntax check with pep8 (recommended) it won't be
> happy with those long lines
> 2) causes all kinds of horizontal scroll issues on some viewers
> 3) there are reasons why I want to split it up.
>
> as a rule, I write
>
> description = """
> first line of text up to 80 cols
> second line of text up to 80cols
> etc.
> """
>
> I find it much cleaner.
Like Jack, I'm (personally) also annoyed of those long lines in the
'module help' output and like his approach of tackling this issue.
However, as usual there are different site policies, so maybe we need
to make things configurable. This is actually something that I have
in mind for quite some time, but never got round to propose it to the
community. Taking this discussion as a trigger, here are my thoughts:
Currently, the output of `module help` (and `module whatis`) is
constructed out of two easyconfig parameters: `description` and
`homepage`. (The `whatis` output can also be overwritten using
the `whatis` easyconfig parameter.) Both are taken verbatim,
simply concatenated with a `-` as separator, and written into the
modulefile. The following proposal is intended to provide more
flexibility for site-specific customizations by introducing some
additional (but optional) easyconfig parameters.
usage
Generic (or potentially site-specific) usage instructions. This
may, for example include a brief description of the main commands,
environment variables that are provided by the modulefile, how to
include headers and link against a library, or that one has to be
part of a special UNIX group to be able to use a software package.
Type: free-form text
docpath
Path to documentation installed by the package, relative to
$EBROOT<pkg>.
Type: List of strings
support
Package-specific support/bug report e-mail address, e.g.,
"supp...@package.org"
Type: Single string (or list?)
contact
Site-specific contact, e.g.,
"Jim Admin <j...@site.edu>, +1 555 123 456"
Type: Single string (or list?)
The `module help` output of an artificial package `foo` may then look
like this:
----- 8< ------ 8< ----- 8< ----- 8< ----- 8< ----- 8< ----- 8< -----
% module help foo/1.0
---------------- Module Specific Help for "foo/1.0" -----------------
Description
===========
The foo package provide some service that can be used to do something.
Its purpose is still somewhat unclear.
Usage
=====
Run 'foo' without parameters to start the graphical user interface.
To use the 'foo' library in your own applications, use
-I$EBROOTFOO/include
when compiling and
-L$EBROOTFOO/lib -lfoo
when linking. Alternatively, you can also use the 'foo-config' utility
using the '--cppflags', '--ldflags' and '--libs' command-line options.
More information
================
- Homepage: http://www.foo.org
- Local documentation:
- $EBROOTFOO/share/doc/foo/UserGuide.pdf
- $EBROOTFOO/share/doc/foo/html/index.html
- Support/bug reports: supp...@foo.org
- Contact: Jim Admin <j...@site.edu>, +1 555 123 456
----- >8 ----- >8 ----- >8 ----- >8 ----- >8 ----- >8 ----- >8 -----
Instead, `module whatis` would only print the description:
----- 8< ------ 8< ----- 8< ----- 8< ----- 8< ----- 8< ----- 8< -----
% module whatis foo/1.0
foo/1.0 : Description: The foo package provide some service that can
be used to do something. Its purpose is still somewhat unclear.
----- >8 ----- >8 ----- >8 ----- >8 ----- >8 ----- >8 ----- >8 -----
For the free-form text fields, we could implement some sort of
automatic line wrapping to a configurable width limit (including
'none'). Python's `textwrap` functionality may serve as a starting
point, however, it has several limitations (only single paragraph,
need to use `dedent` to be useful, ...). So we probably need some
preprocessing to support, e.g., multiple paragraphs, (sub-)section
headings, bullet lists, etc. (kind of a markdown processing).
What do you think?
> (unfortunately, I don't think EasyBuild has a tag for a "module load"
> message).
It should be fairly straightforward to support that as well (if
you want to hard-code this into the modulefile rather than using
Lmod's admin.list approach).
Markus
--
Dr. Markus Geimer
Juelich Supercomputing Centre
Institute for Advanced Simulation
Forschungszentrum Juelich GmbH
52425 Juelich, Germany
Phone: +49-2461-61-1773
Fax: +49-2461-61-6656
E-mail: m.gei...@fz-juelich.de
WWW: http://www.fz-juelich.de/jsc/
------------------------------------------------------------------------------------------------
------------------------------------------------------------------------------------------------
Forschungszentrum Juelich GmbH
52425 Juelich
Sitz der Gesellschaft: Juelich
Eingetragen im Handelsregister des Amtsgerichts Dueren Nr. HR B 3498
Vorsitzender des Aufsichtsrats: MinDir Dr. Karl Eugen Huthmacher
Geschaeftsfuehrung: Prof. Dr.-Ing. Wolfgang Marquardt (Vorsitzender),
Karsten Beneke (stellv. Vorsitzender), Prof. Dr.-Ing. Harald Bolt,
Prof. Dr. Sebastian M. Schmidt
------------------------------------------------------------------------------------------------
------------------------------------------------------------------------------------------------
