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

[mr-c]

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.

[mr-c]

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

[h-2]

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

[h-2]

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

[mr-c]

@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;
      |         ^~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

[mr-c]

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]

[h-2]

I'll have a look sometime this week!

[h-2]

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]");

[h-2]

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

[mr-c]

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

[sarahet]

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?