Skip to content

a few issues with the generated unix man(ual) pages #124

Open
Open
a few issues with the generated unix man(ual) pages#124

Description

@mr-c
mr-c
opened on Jan 23, 2019

Thank you for the unix man(ual) pages!

The Debian linter found a few issues with them. This might be more of a seqan issue, though.

https://lintian.debian.org/maintainer/debian-med-packaging@lists.alioth.debian.org.html#lambda-align2

1st issue:

manpage-has-bad-whatis-entry
For manual pages that document multiple programs, functions, files, or other things, the part before "-" should list each separated by a comma and a space. Each thing listed must not contain spaces; a man page for a two-part command like "fs listacl" must use something like "fs_listacl" in the "NAME" section so that it can be parsed by lexgrog.

  • usr/share/man/man1/lambda2-mkindexn.1.gz
  • usr/share/man/man1/lambda2-mkindexp.1.gz
  • usr/share/man/man1/lambda2-searchn.1.gz
  • usr/share/man/man1/lambda2-searchp.1.gz

using lambda2-mkindexn.1.gz as an example:

.TH LAMBDA2 MKINDEXN 1 "Jan 22 2019" "lambda2 mkindexn 2.0.0" ""
.SH NAME
lambda2 mkindexn \- the Local Aligner for Massive Biological DatA
.SH SYNOPSIS
\fBlambda2 mkindexn\fP [\fIOPTIONS\fP] \-d DATABASE.fasta [-i INDEX.lambda]\fP

should be

.TH LAMBDA2_MKINDEXN 1 "Jan 22 2019" "lambda2 mkindexn 2.0.0" ""
.SH NAME
lambda2_mkindexn \- the Local Aligner for Massive Biological DatA
.SH SYNOPSIS
\fBlambda2 mkindexn\fP [\fIOPTIONS\fP] \-d DATABASE.fasta [-i INDEX.lambda]\fP

The NAME can't have spaces between the subcommand parts but they are allowed in the SYNOPSIS

2nd issue:

manpage-section-mismatch
.TH title section [extra1] [extra2] [extra3]

In the example above we have .TH LAMBDA2 MKINDEXN 1 "Jan 22 2019" "lambda2 mkindexn 2.0.0" "", and again the space between LAMBDA2 and MKINDEXN shouldn't be there. Makes it look as if the section is "MKINDEXN" instead of section 1.

Activity

  1. mr-c commented on Jan 23, 2019

    @mr-c
    mr-c
    on Jan 23, 2019
    ContributorAuthor

    I think this is the part of seqan that needs fixing:

    https://github.com/seqan/seqan/blob/develop/include/seqan/arg_parse/tool_doc.h#L1555

  2. h-2 commented on Feb 19, 2020

    @h-2
    h-2
    on Feb 19, 2020
    Member

    Are these things still a problem with the SeqAn3 argument parser?

  3. h-2 commented on Aug 15, 2022

    @h-2
    h-2
    on Aug 15, 2022
    Member

    Closing this. If it still exists with the lambda3 branch, please reopen.

  4. h-2
    closed this as completedon Aug 15, 2022

  5. mr-c commented on Sep 20, 2022

    @mr-c
    mr-c
    on Sep 20, 2022
    ContributorAuthor

    @h-2 I can't get the lambda3 branch to build

    From a fresh checkout today:

    -- These dependencies were found:
     OPENMP     TRUE      -fopenmp
     ZLIB       TRUE      1.2.11
     BZIP2      TRUE      1.0.8
     SEQAN      TRUE      2.4.1
     SEQAN3     TRUE      3.3.0-rc.1
-- The requirements were met.
-- The C compiler identification is GNU 12.2.0

[…]

In file included from /home/michael/src/lambda/submodules/seqan/include/seqan/basic/basic_fundamental.h:82,
                 from /home/michael/src/lambda/submodules/seqan/include/seqan/basic.h:58,
                 from /home/michael/src/lambda/submodules/seqan/include/seqan/align.h:55,
                 from /home/michael/src/lambda/src/seqan2seqan3.hpp:55:
/home/michael/src/lambda/submodules/seqan/include/seqan/basic/array_construct_destruct.h: In instantiation of ‘static void seqan::ValueConstructor_::construct(TIterator) [with TIterator = std::ranges::take_view<std::ranges::drop_view<seqan3::detail::view_translate_single<std::ranges::ref_view<std::vector<seqan3::dna5> > > > >*]’:
/home/michael/src/lambda/submodules/seqan/include/seqan/basic/array_construct_destruct.h:286:28:   required from ‘void seqan::valueConstruct(TIterator) [with TIterator = std::ranges::take_view<std::ranges::drop_view<seqan3::detail::view_translate_single<std::ranges::ref_view<std::vector<seqan3::dna5> > > > >*]’
/home/michael/src/lambda/submodules/seqan/include/seqan/basic/holder_tristate.h:589:27:   required from ‘void seqan::create(Holder<TValue, Tag<Tristate_> >&) [with TValue = std::ranges::take_view<std::ranges::drop_view<seqan3::detail::view_translate_single<std::ranges::ref_view<std::vector<seqan3::dna5> > > > >]’
/home/michael/src/lambda/submodules/seqan/include/seqan/basic/holder_tristate.h:863:15:   required from ‘typename seqan::Reference<seqan::Holder<TValue, seqan::Tag<seqan::Tristate_> > >::Type seqan::value(Holder<TValue, Tag<Tristate_> >&) [with TValue = std::ranges::take_view<std::ranges::drop_view<seqan3::detail::view_translate_single<std::ranges::ref_view<std::vector<seqan3::dna5> > > > >; typename Reference<Holder<TValue, Tag<Tristate_> > >::Type = std::ranges::take_view<std::ranges::drop_view<seqan3::detail::view_translate_single<std::ranges::ref_view<std::vector<seqan3::dna5> > > > >&]’
/home/michael/src/lambda/submodules/seqan/include/seqan/align/gaps_array.h:427:10:   required from ‘void seqan::assignSource(Gaps<TSequence, Tag<ArrayGaps_> >&, const TSequence2&) [with TSequence = std::ranges::take_view<std::ranges::drop_view<seqan3::detail::view_translate_single<std::ranges::ref_view<std::vector<seqan3::dna5> > > > >; TSequence2 = std::ranges::take_view<std::ranges::drop_view<seqan3::detail::view_translate_single<std::ranges::ref_view<std::vector<seqan3::dna5> > > > >]’
/home/michael/src/lambda/src/search_algo.hpp:863:24:   [ skipping 2 instantiation contexts, use -ftemplate-backtrace-limit=0 to disable ]
/home/michael/src/lambda/src/search_algo.hpp:1275:27:   required from ‘void iterateMatches(TLocalHolder&) [with TLocalHolder = LocalDataHolder<GlobalDataHolder<DbIndexType::FM_INDEX, AlphabetEnum::DNA5, AlphabetEnum::AMINO_ACID, AlphabetEnum::AMINO_ACID, AlphabetEnum::DNA5> >]’
/home/michael/src/lambda/src/search.cpp:395:31:   required from ‘void realMain(const LambdaOptions&) [with DbIndexType c_indexType = DbIndexType::FM_INDEX; AlphabetEnum c_origSbjAlph = AlphabetEnum::DNA5; AlphabetEnum c_transAlph = AlphabetEnum::AMINO_ACID; AlphabetEnum c_redAlph = AlphabetEnum::AMINO_ACID; AlphabetEnum c_origQryAlph = AlphabetEnum::DNA5]’
/home/michael/src/lambda/src/search.cpp:314:100:   required from ‘void argConv3(const LambdaOptions&) [with DbIndexType c_indexType = DbIndexType::FM_INDEX; AlphabetEnum c_origSbjAlph = AlphabetEnum::DNA5; AlphabetEnum c_transAlph = AlphabetEnum::AMINO_ACID; AlphabetEnum c_redAlph = AlphabetEnum::AMINO_ACID]’
/home/michael/src/lambda/src/search.cpp:297:108:   required from ‘void argConv2b(const LambdaOptions&) [with DbIndexType c_indexType = DbIndexType::FM_INDEX; AlphabetEnum c_origSbjAlph = AlphabetEnum::DNA5]’
/home/michael/src/lambda/src/search.cpp:261:66:   required from ‘void argConv1(const LambdaOptions&) [with DbIndexType c_indexType = DbIndexType::FM_INDEX]’
/home/michael/src/lambda/src/search.cpp:241:51:   required from here
/home/michael/src/lambda/submodules/seqan/include/seqan/basic/array_construct_destruct.h:244:9: error: no matching function for call to ‘std::ranges::take_view<std::ranges::drop_view<seqan3::detail::view_translate_single<std::ranges::ref_view<std::vector<seqan3::dna5> > > > >::take_view()’
  244 |         new( (void*) & value(it) ) TNonConstValue;
      |         ^~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

  6. mr-c commented on Sep 20, 2022

    @mr-c
    mr-c
    on Sep 20, 2022
    ContributorAuthor

    Okay, compiling with gcc 11 works; and there is still a problem

    Here are my recommended fixes, using lambda3 searchp --export-help man

    $ diff ./lambda3_searchp.1 ./lambda3_searchp.fixed.1 
1c1
< .TH LAMBDA3-SEARCHP 1 "Sep 20 2022" "lambda3-searchp 3.0.0" ""
---
> .TH LAMBDA3_SEARCHP 1 "Sep 20 2022" "lambda3-searchp 3.0.0" ""
3c3
< lambda3-searchp \- the Local Aligner for Massive Biological DatA
---
> lambda3_searchp \- the Local Aligner for Massive Biological DatA
5c5
< \fB[\fIOPTIONS\fP]\fP \fI-q QUERY.fasta\fP \fI-i INDEX.lambda\fP [\fI-o output.m8\fP]
---
> \fIlambda2 searchp\fP \fB[\fIOPTIONS\fP]\fP \fI-q QUERY.fasta\fP \fI-i INDEX.lambda\fP [\fI-o output.m8\fP]

  7. h-2 commented on Sep 20, 2022

    @h-2
    h-2
    on Sep 20, 2022
    Member

    I'll have a look sometime this week!

  8. h-2
    reopened this on Sep 20, 2022

  9. h-2 commented on Sep 21, 2022

    @h-2
    h-2
    on Sep 21, 2022
    Member

    To be honest, I have no clue about the man-page formats. We are just using the seqan3 argument parser as recommend. The main problem seems to be - instead of _ ... ?

    Would the following changes fix this for you:

    https://github.com/seqan/lambda/blob/lambda3/src/search_options.hpp#L115

    -   std::string programName = "lambda3-" + std::string(argv[0]);
+   std::string programName = "lambda3_" + std::string(argv[0]);

    https://github.com/seqan/lambda/blob/lambda3/src/search_options.hpp#L126

    -    parser.info.synopsis.push_back(
+    parser.info.synopsis.push_back(std::string{"\\fIlambda3 "} +  std::string(argv[0]) + "\\fP "
      "[\\fIOPTIONS\\fP] \\fI-q QUERY.fasta\\fP \\fI-i INDEX.lambda\\fP [\\fI-o output.m8\\fP]");

  10. h-2 commented on Jul 13, 2023

    @h-2
    h-2
    on Jul 13, 2023
    Member

    Can you still reproduce the problems with the current lambda3-branch? Does it build for you now?

  11. mr-c commented on Jul 13, 2023

    @mr-c
    mr-c
    on Jul 13, 2023
    ContributorAuthor

    The search* manpages are warning/error-free; thanks!

    The mkindex* manpages have some issues with

    paragraph filling. They are usually related to long lines. Justifying text on the left hand side can help with adjustments. Hyphenation can help with breaks.
    For more information, please see "Manipulating Filling and Adjusting" and "Manipulating Hyphenation" in the Groff manual

    LC_ALL=C.UTF-8 MANROFFSEQ='' MANWIDTH=80 man --warnings -E UTF-8 -l -Tutf8 -Z ./lambda3_mkindexn.1  >/dev/null
troff: <standard input>:38: warning [p 1, 8.7i]: cannot adjust line

  12. sarahet commented on Jul 21, 2023

    @sarahet
    sarahet
    on Jul 21, 2023
    Member

    Hi - could this link be the problem by chance?

    lambda/src/mkindex_options.hpp

    Line 120 in cf59351

    "ftp://ftp.uniprot.org/pub/databases/uniprot/current_release/knowledgebase/idmapping/ .",

    At least it is longer than 80 char and can't just be split. If so, do you have a recommendation how you usually handle this?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions