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

mr-c · 2019-01-23T15:54:51Z

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.

The text was updated successfully, but these errors were encountered:

mr-c · 2019-01-23T19:57:46Z

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 · 2020-02-19T17:56:14Z

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

h-2 · 2022-08-15T13:33:35Z

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

mr-c · 2022-09-20T14:34:20Z

@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 · 2022-09-20T14:48:31Z

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 · 2022-09-20T18:16:21Z

I'll have a look sometime this week!

h-2 · 2022-09-21T16:20:55Z

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 · 2023-07-13T15:52:37Z

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

mr-c · 2023-07-13T16:51:24Z

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 · 2023-07-21T11:43:26Z

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?

h-2 closed this as completed Aug 15, 2022

mr-c mentioned this issue Sep 20, 2022

gcc 12 + lambda3 branch == compliation error #189

Closed

h-2 reopened this Sep 20, 2022

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

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

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

mr-c commented Jan 23, 2019

mr-c commented Jan 23, 2019

h-2 commented Feb 19, 2020

h-2 commented Aug 15, 2022

mr-c commented Sep 20, 2022 •

edited

mr-c commented Sep 20, 2022

h-2 commented Sep 20, 2022

h-2 commented Sep 21, 2022

h-2 commented Jul 13, 2023

mr-c commented Jul 13, 2023

sarahet commented Jul 21, 2023

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

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

Comments

mr-c commented Jan 23, 2019

mr-c commented Jan 23, 2019

h-2 commented Feb 19, 2020

h-2 commented Aug 15, 2022

mr-c commented Sep 20, 2022 • edited

mr-c commented Sep 20, 2022

h-2 commented Sep 20, 2022

h-2 commented Sep 21, 2022

h-2 commented Jul 13, 2023

mr-c commented Jul 13, 2023

sarahet commented Jul 21, 2023

mr-c commented Sep 20, 2022 •

edited