Lightning: manpages

[ZmnSCPxj]

As we already have manpages for many commands, we should go whole-hog and make manpages for all commands.

We even have manpages for obscure commands (autocleaninvoice) but some important commands are missing description!

• [x] fundchannel #1463
• [x] connect #1427
• [x] disconnect
• [x] listpeers
• [x] listchannels
• [x] close #1355
• [x] withdraw #1427
• [x] newaddr #1427
• [x] listfunds #1427
• [x] lightningd itself #2899

[wythe]

Agreed, this is something I've had my eye on. I've wound down some of my other activities and plan to spend a lot more time on this project.

[fixone]

I've created PR #1406 that covers 2 of the 8 still needed manpages

[wythe]

As far as I can tell, the actual JSON RPC interface is not documented anywhere (I figured it out using printf). Maybe we could use a lightning-rpc manpage. Or, the yet to be written lightningd page will define it.

[ZmnSCPxj]

We are supposedly following this spec for JSON-RPC: http://www.jsonrpc.org/specification

Note however that we do not support batch command processing as far as I can tell.

[wythe]

That makes sense. Thanks. I knew I was missing something.

[ghost]

I'm happy to pick this one up and create man pages for the remaining.

[ghost]

Are you happy for me to open an issue for each page required and then track overall progress on here? I can see some taking less time that others and suspect that the page for lightningd could be quite in depth.

[wythe]

So far we just point everyone to this issue instead of opening a new one for each. I suggest you just write them one at a time, making a PR for each. disconnect looks like a good one to start with.

And yes, lightningd is a bit daunting!

[ghost]

Happy New Year all! I've taken a first look at producing a lightningd manpage but can see that there is a lightningd-config.5.txt document containing much of what I'd expect to go into it. Is there an additional need for a lightningd manpage and if so could you outline the requirements?

[hawkmauk]

Had a spring clean of my github accounts now that private repositories are available for basic accounts so apologies for the ghosting.
I'd like to work towards getting this issue closed as I believe the only item outstanding now is lighningd.
Using the bitcoind manpage as a template, the lightningd-config document should be renamed and reworked to be less lightningd-config centric. I'd be keen to get some feedback on this suggestion before proceeding - is this the best forum for that?

[wythe]

For the initial lightningd manpage, my thoughts are that it might be best to just present a concise overview with pointers to other manpages for the details. Take a look at the git manpage for inspiration.

It also might be a good place to walk the reader through the steps of opening a channel and processing payments. This would be similar to giteveryday(7), but I don't think requires a separate manpage yet.

I agree that lightningd-config could/should be reworked like @host and @hawkmauk suggests, but maybe that can be done in a later step.

My two cents!

[hawkmauk]

Thanks for the feedback, I like the idea of including steps for actions such as opening channels and making payments. I would expect the man page to include command line args though which would only serve to duplicate what is in lighningd-config which is my main concern.

[ZmnSCPxj]

The lightningd could show the more likely of interest config options, then point to lightningd-config for details

[ZmnSCPxj]

Only one manpage left, hopefully we can complete before 0.7.2.