>  🔗 https://github.com/praiskup/argparse-manpage

 
Ok, I tried the thing, really quick.

It wants the name of the function where it can get the parser. So if the
parser setuip is moved to a separate function:

```py
def get_parser():
    parser = parser = argparse.ArgumentParser(description='A command line gemini client.')
    parser.add_argument('--bookmarks', action='store_true',
                        help='start with your list of bookmarks')
	  […]
    return parser

def main():
    parser = get_parser()
          […]
```

then you can do “argparse-manpage offpunk.py --function get_parser” and it
will spit out a troff page.

Cheers,

-- 
Kʟᴀᴜꜱ Aʟᴇxᴀɴᴅᴇʀ Sᴇɪꜱᴛʀᴜᴘ 🇩🇰
https://magnetic-ink.dk/kas

Hi all,

From Ploum:
> But I feel it would be a lot better to maintain our own upstream
> manpage.

I agree.  I wrapped up a Debian specific manual page, but I can
easily forget to update the manual on next upstream version.
Furthermore, an upstream manual page will be more beneficial for
all distributions, and not only Debian and derivatives.
Besides, this translates in a note in the Debian linter lintian,
although an issue of pedantic severity.  ;)

> Another option is maintaining a markdown file that would be converted to
> groff by packagers using Pandoc

From my perspective, I'm not against pandoc usage for producing
documentation in multiple formats: packaging scripts provide all
the necessary hooks to build documentation for packages, and it
is somewhat customary to use pandoc in a number of contexts, so
there are many eyeballs on this package when things go wrong.  A
lightweight distribution may not be as well served though.

Klaus Alexander Seistrup, on 2023-03-03:
> >  🔗 https://github.com/praiskup/argparse-manpage

From a dependency tree perspective, argparse-manpage depends
only on the python3 interpreter.  From my Debian packager's
perspective, it is already available in Debian.  Overall this
should be rather easy to integrate in the package building
routine.  With offpunk already depending on python3, the added
complexity is minimal here.

phoebos, two days ago:
> > > Manpages are essential in my opinion. Étienne's manpage is written in
> > > man(7), the historical markup in which you use formatting to describe
> > > syntax. I prefer mdoc(7), which uses _semantic markup_ which is then
> > > formatted consistently. mdoc is designed to be easy to write. It is just
> > > as portable as man, and generally better documented.

I was not aware of mandoc(1) and the mdoc(7) format.  This
approach is also quite appealing, especially in the case Ploum
were to consider the manual page as a standalone document
instead of an autogenerated one.  The dependency tree of mandoc
is also very light weight: the libc and the libz.  This package
is already available in Debian, should I need it to proceed to
the packaging of offpunk.

Have a nice day,  :)
-- 
Étienne Mollier <emollier@emlwks999.eu>
Fingerprint:  8f91 b227 c7d6 f2b1 948c  8236 793c f67e 8f0d 11da
Sent from /dev/pts/1, please excuse my verbosity.

On 23/03/06 09:26, Étienne Mollier - emollier at emlwks999.eu wrote:
>
>phoebos, two days ago:
>> > > Manpages are essential in my opinion. Étienne's manpage is written in
>> > > man(7), the historical markup in which you use formatting to describe
>> > > syntax. I prefer mdoc(7), which uses _semantic markup_ which is then
>> > > formatted consistently. mdoc is designed to be easy to write. It is just
>> > > as portable as man, and generally better documented.
>
>I was not aware of mandoc(1) and the mdoc(7) format.  This
>approach is also quite appealing, especially in the case Ploum
>were to consider the manual page as a standalone document
>instead of an autogenerated one.  The dependency tree of mandoc
>is also very light weight: the libc and the libz.  This package
>is already available in Debian, should I need it to proceed to
>the packaging of offpunk.

Thanks for all the inputs. I really think mdoc is the way to go. I
should take the time to learn it and produce a first version.
--
Ploum - Lionel Dricot
Blog: https://www.ploum.net
Livres: https://ploum.net/livres.html

Ploum wrote:

> Thanks for all the inputs. I really think mdoc is the way to go.
> I should take the time to learn it and produce a first version.

I shan't decide how you spend your time, but before you sit your ass
down and learn how mdoc works, please try the Python module
argparse-manpage first: If you move the parser setup to a separate
function then argparse-manpage will create a full-fledged troff man
page directly from the offpunk.py script, meaning that the manpage
will automatically be rebuild whenever the offpunk options change.
There is literally zero markup language to be learned first.

In ArchLinux it is included as community/python-argparse-manpage.

-- 
Kʟᴀᴜꜱ Aʟᴇxᴀɴᴅᴇʀ Sᴇɪꜱᴛʀᴜᴘ 🇩🇰
https://magnetic-ink.dk/kas

On Mon, Mar 06, 2023 at 20:58:45 +0000, Ploum wrote:
> >I was not aware of mandoc(1) and the mdoc(7) format.  This
> >approach is also quite appealing, especially in the case Ploum
> >were to consider the manual page as a standalone document
> >instead of an autogenerated one.  The dependency tree of mandoc
> >is also very light weight: the libc and the libz.  This package
> >is already available in Debian, should I need it to proceed to
> >the packaging of offpunk.

Note that groff also supports mdoc(7); mandoc is not necessary.

> Thanks for all the inputs. I really think mdoc is the way to go. I
> should take the time to learn it and produce a first version.

You are welcome to use the page I wrote. It doesn't take too long to
learn! There is also a tutorial available as groff_mdoc(7).

phoebos