Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Use lowdown(1), not mrkd, to generate man pages from Markdown #5437

Closed
rustyrussell opened this issue Jul 18, 2022 · 6 comments
Closed

Use lowdown(1), not mrkd, to generate man pages from Markdown #5437

rustyrussell opened this issue Jul 18, 2022 · 6 comments
Assignees
@rustyrussell
Labels
docs
Milestone
v22.11

Comments

@rustyrussell
Copy link
Contributor

mrkd is pretty bad, complicates dependencies.

We could use lowdown, and also reformat our pages a bit to make them prettier and more consistent.

Command is something like:

lowdown -s --out-no-smarty -Tman -m "title:LIGHTNINGD-CONFIG" -m "section:5" -m "shiftheadinglevelby:-1"
@rustyrussell rustyrussell added this to the v22.10 milestone Jul 18, 2022
@rustyrussell rustyrussell self-assigned this Jul 18, 2022
@vincenzopalazzo
Copy link
Contributor

Concept ack.

BTW what is the milestone 22.10? should like a TODO :)

@wtogami
Copy link
Contributor

wtogami commented Jul 19, 2022

I'm hoping this can be done for v0.12 because mrkd is a serious headache obstructing packaging CLN in Fedora and EPEL. I need to package all the deps for offline builds and there are policies against more than one version of a package which makes mrkd dead in the water.

rustyrussell added a commit to rustyrussell/lightning that referenced this issue Jul 20, 2022
@rustyrussell
Makefile: replace mrkd with lowdown(1).
fcf882d 
Here's the before-vs-after comparison (ignoring whitespace changes):

```diff
 --- /tmp/before	2022-07-20 21:52:44.336641810 +0930
 +++ /tmp/after	2022-07-20 21:55:54.355487769 +0930
 @@ -1,7 +1,7 @@
 -LIGHTNING-CLI(1)                                          lightning-cli                                         LIGHTNING-CLI(1)
 +LIGHTNING-CLI(1)                                                                                                LIGHTNING-CLI(1)
  
  NAME
 -       lightning-cli - Control lightning daemon
 +       lightning-cli -- Control lightning daemon
  
  SYNOPSIS
         lightning-cli [OPTIONS] command
 @@ -14,10 +14,7 @@
  
          --conf=PATH Sets configuration file (default: lightning-dir/config ).
  
 -        --network=network
 -        --mainnet
 -        --testnet
 -        --signet Sets network explicitly.
 +       --network=network --mainnet --testnet --signet Sets network explicitly.
  
          --rpc-file=FILE Named pipe to use to talk to lightning daemon: default is lightning-rpc in the lightning directory.
  
 @@ -43,8 +40,8 @@
  
          --version/-V Print version number to standard output and exit.
  
 -        allow-deprecated-apis=BOOL  Enable  deprecated options. It defaults to true, but you should set it to false when testing
 -       to ensure that an upgrade won't break your configuration.
 +       allow-deprecated-apis=BOOL Enable deprecated options. It defaults to true, but you should set it to false when testing to
 +       ensure that an upgrade won't break your configuration.
  
  COMMANDS
         lightning-cli simply uses the JSON RPC interface to talk to lightningd, and prints the results. Thus the commands  avail‐
 @@ -67,7 +64,7 @@
  
         lightning-cli help
  
 -              1.     Fund a 10k sat channel using uncomfirmed outputs
 +       2.     Fund a 10k sat channel using uncomfirmed outputs
  
         lightning-cli --keywords fundchannel id=028f...ae7d amount=10000sat minconf=0
  
 @@ -84,4 +81,4 @@
         Note: the modules in the ccan/ directory have their own licenses, but the rest of the code is covered  by  the  BSD-style
         MIT license.
  
 -                                                                                                                LIGHTNING-CLI(1)
 +Core Lightning v0.11.0.1-350-gac2e137                                                                           LIGHTNING-CLI(1)
```

Signed-off-by: Rusty Russell <[email protected]>
Fixes: ElementsProject#5437
@grubles
Copy link
Contributor

grubles commented Jul 21, 2022

Is there a reason for the whitespace changes to be ignored? Seems like the example changes in rustyrussell@fcf882d might be harder to read than when using mrkd. Or is that something to be fixed later with "also reformat our pages a bit to make them prettier and more consistent"?

@jb55
Copy link
Collaborator

jb55 commented Jul 21, 2022

ACK, switching to lowdown was trivial on my linux distro and it seemed to work ok

@rustyrussell
Copy link
Contributor Author

OTOH, this is not a regression since previous versions; it has long been this way.

@whitslack
Copy link
Collaborator

Chiming in (a little late to the party)… Mrkd is also an obstruction for Gentoo packaging since it fails to work with the current generation of Mistune. Thus, anyone who wants to build CLN with documentation (USE="doc") is forced to have their Mistune downgraded, which may not even be possible if other installed packages strictly depend on a newer version.

Glad to see there's a resolution in the pipeline. 🙂

rustyrussell added a commit to rustyrussell/lightning that referenced this issue Sep 5, 2022
@rustyrussell
Makefile: replace mrkd with lowdown(1).
fae9d24 
Here's the before-vs-after comparison (ignoring whitespace changes):

```diff
 --- /tmp/before	2022-07-20 21:52:44.336641810 +0930
 +++ /tmp/after	2022-07-20 21:55:54.355487769 +0930
 @@ -1,7 +1,7 @@
 -LIGHTNING-CLI(1)                                          lightning-cli                                         LIGHTNING-CLI(1)
 +LIGHTNING-CLI(1)                                                                                                LIGHTNING-CLI(1)
  
  NAME
 -       lightning-cli - Control lightning daemon
 +       lightning-cli -- Control lightning daemon
  
  SYNOPSIS
         lightning-cli [OPTIONS] command
 @@ -14,10 +14,7 @@
  
          --conf=PATH Sets configuration file (default: lightning-dir/config ).
  
 -        --network=network
 -        --mainnet
 -        --testnet
 -        --signet Sets network explicitly.
 +       --network=network --mainnet --testnet --signet Sets network explicitly.
  
          --rpc-file=FILE Named pipe to use to talk to lightning daemon: default is lightning-rpc in the lightning directory.
  
 @@ -43,8 +40,8 @@
  
          --version/-V Print version number to standard output and exit.
  
 -        allow-deprecated-apis=BOOL  Enable  deprecated options. It defaults to true, but you should set it to false when testing
 -       to ensure that an upgrade won't break your configuration.
 +       allow-deprecated-apis=BOOL Enable deprecated options. It defaults to true, but you should set it to false when testing to
 +       ensure that an upgrade won't break your configuration.
  
  COMMANDS
         lightning-cli simply uses the JSON RPC interface to talk to lightningd, and prints the results. Thus the commands  avail‐
 @@ -67,7 +64,7 @@
  
         lightning-cli help
  
 -              1.     Fund a 10k sat channel using uncomfirmed outputs
 +       2.     Fund a 10k sat channel using uncomfirmed outputs
  
         lightning-cli --keywords fundchannel id=028f...ae7d amount=10000sat minconf=0
  
 @@ -84,4 +81,4 @@
         Note: the modules in the ccan/ directory have their own licenses, but the rest of the code is covered  by  the  BSD-style
         MIT license.
  
 -                                                                                                                LIGHTNING-CLI(1)
 +Core Lightning v0.11.0.1-350-gac2e137                                                                           LIGHTNING-CLI(1)
```

Signed-off-by: Rusty Russell <[email protected]>
Fixes: ElementsProject#5437
rustyrussell added a commit to rustyrussell/lightning that referenced this issue Sep 6, 2022
@rustyrussell
Makefile: replace mrkd with lowdown(1).
e1e7395 
Here's the before-vs-after comparison (ignoring whitespace changes):

```diff
 --- /tmp/before	2022-07-20 21:52:44.336641810 +0930
 +++ /tmp/after	2022-07-20 21:55:54.355487769 +0930
 @@ -1,7 +1,7 @@
 -LIGHTNING-CLI(1)                                          lightning-cli                                         LIGHTNING-CLI(1)
 +LIGHTNING-CLI(1)                                                                                                LIGHTNING-CLI(1)
  
  NAME
 -       lightning-cli - Control lightning daemon
 +       lightning-cli -- Control lightning daemon
  
  SYNOPSIS
         lightning-cli [OPTIONS] command
 @@ -14,10 +14,7 @@
  
          --conf=PATH Sets configuration file (default: lightning-dir/config ).
  
 -        --network=network
 -        --mainnet
 -        --testnet
 -        --signet Sets network explicitly.
 +       --network=network --mainnet --testnet --signet Sets network explicitly.
  
          --rpc-file=FILE Named pipe to use to talk to lightning daemon: default is lightning-rpc in the lightning directory.
  
 @@ -43,8 +40,8 @@
  
          --version/-V Print version number to standard output and exit.
  
 -        allow-deprecated-apis=BOOL  Enable  deprecated options. It defaults to true, but you should set it to false when testing
 -       to ensure that an upgrade won't break your configuration.
 +       allow-deprecated-apis=BOOL Enable deprecated options. It defaults to true, but you should set it to false when testing to
 +       ensure that an upgrade won't break your configuration.
  
  COMMANDS
         lightning-cli simply uses the JSON RPC interface to talk to lightningd, and prints the results. Thus the commands  avail‐
 @@ -67,7 +64,7 @@
  
         lightning-cli help
  
 -              1.     Fund a 10k sat channel using uncomfirmed outputs
 +       2.     Fund a 10k sat channel using uncomfirmed outputs
  
         lightning-cli --keywords fundchannel id=028f...ae7d amount=10000sat minconf=0
  
 @@ -84,4 +81,4 @@
         Note: the modules in the ccan/ directory have their own licenses, but the rest of the code is covered  by  the  BSD-style
         MIT license.
  
 -                                                                                                                LIGHTNING-CLI(1)
 +Core Lightning v0.11.0.1-350-gac2e137                                                                           LIGHTNING-CLI(1)
```

Signed-off-by: Rusty Russell <[email protected]>
Fixes: ElementsProject#5437
niftynei pushed a commit to niftynei/lightning that referenced this issue Sep 13, 2022
@rustyrussell @niftynei
Makefile: replace mrkd with lowdown(1).
76b57a2 
Here's the before-vs-after comparison (ignoring whitespace changes):

```diff
 --- /tmp/before	2022-07-20 21:52:44.336641810 +0930
 +++ /tmp/after	2022-07-20 21:55:54.355487769 +0930
 @@ -1,7 +1,7 @@
 -LIGHTNING-CLI(1)                                          lightning-cli                                         LIGHTNING-CLI(1)
 +LIGHTNING-CLI(1)                                                                                                LIGHTNING-CLI(1)
  
  NAME
 -       lightning-cli - Control lightning daemon
 +       lightning-cli -- Control lightning daemon
  
  SYNOPSIS
         lightning-cli [OPTIONS] command
 @@ -14,10 +14,7 @@
  
          --conf=PATH Sets configuration file (default: lightning-dir/config ).
  
 -        --network=network
 -        --mainnet
 -        --testnet
 -        --signet Sets network explicitly.
 +       --network=network --mainnet --testnet --signet Sets network explicitly.
  
          --rpc-file=FILE Named pipe to use to talk to lightning daemon: default is lightning-rpc in the lightning directory.
  
 @@ -43,8 +40,8 @@
  
          --version/-V Print version number to standard output and exit.
  
 -        allow-deprecated-apis=BOOL  Enable  deprecated options. It defaults to true, but you should set it to false when testing
 -       to ensure that an upgrade won't break your configuration.
 +       allow-deprecated-apis=BOOL Enable deprecated options. It defaults to true, but you should set it to false when testing to
 +       ensure that an upgrade won't break your configuration.
  
  COMMANDS
         lightning-cli simply uses the JSON RPC interface to talk to lightningd, and prints the results. Thus the commands  avail‐
 @@ -67,7 +64,7 @@
  
         lightning-cli help
  
 -              1.     Fund a 10k sat channel using uncomfirmed outputs
 +       2.     Fund a 10k sat channel using uncomfirmed outputs
  
         lightning-cli --keywords fundchannel id=028f...ae7d amount=10000sat minconf=0
  
 @@ -84,4 +81,4 @@
         Note: the modules in the ccan/ directory have their own licenses, but the rest of the code is covered  by  the  BSD-style
         MIT license.
  
 -                                                                                                                LIGHTNING-CLI(1)
 +Core Lightning v0.11.0.1-350-gac2e137                                                                           LIGHTNING-CLI(1)
```

Signed-off-by: Rusty Russell <[email protected]>
Fixes: ElementsProject#5437
whitslack pushed a commit to whitslack/lightning that referenced this issue Oct 8, 2022
@rustyrussell @whitslack
Makefile: replace mrkd with lowdown(1).
e25295b 
Here's the before-vs-after comparison (ignoring whitespace changes):

```diff
 --- /tmp/before	2022-07-20 21:52:44.336641810 +0930
 +++ /tmp/after	2022-07-20 21:55:54.355487769 +0930
 @@ -1,7 +1,7 @@
 -LIGHTNING-CLI(1)                                          lightning-cli                                         LIGHTNING-CLI(1)
 +LIGHTNING-CLI(1)                                                                                                LIGHTNING-CLI(1)
  
  NAME
 -       lightning-cli - Control lightning daemon
 +       lightning-cli -- Control lightning daemon
  
  SYNOPSIS
         lightning-cli [OPTIONS] command
 @@ -14,10 +14,7 @@
  
          --conf=PATH Sets configuration file (default: lightning-dir/config ).
  
 -        --network=network
 -        --mainnet
 -        --testnet
 -        --signet Sets network explicitly.
 +       --network=network --mainnet --testnet --signet Sets network explicitly.
  
          --rpc-file=FILE Named pipe to use to talk to lightning daemon: default is lightning-rpc in the lightning directory.
  
 @@ -43,8 +40,8 @@
  
          --version/-V Print version number to standard output and exit.
  
 -        allow-deprecated-apis=BOOL  Enable  deprecated options. It defaults to true, but you should set it to false when testing
 -       to ensure that an upgrade won't break your configuration.
 +       allow-deprecated-apis=BOOL Enable deprecated options. It defaults to true, but you should set it to false when testing to
 +       ensure that an upgrade won't break your configuration.
  
  COMMANDS
         lightning-cli simply uses the JSON RPC interface to talk to lightningd, and prints the results. Thus the commands  avail‐
 @@ -67,7 +64,7 @@
  
         lightning-cli help
  
 -              1.     Fund a 10k sat channel using uncomfirmed outputs
 +       2.     Fund a 10k sat channel using uncomfirmed outputs
  
         lightning-cli --keywords fundchannel id=028f...ae7d amount=10000sat minconf=0
  
 @@ -84,4 +81,4 @@
         Note: the modules in the ccan/ directory have their own licenses, but the rest of the code is covered  by  the  BSD-style
         MIT license.
  
 -                                                                                                                LIGHTNING-CLI(1)
 +Core Lightning v0.11.0.1-350-gac2e137                                                                           LIGHTNING-CLI(1)
```

Signed-off-by: Rusty Russell <[email protected]>
Fixes: ElementsProject#5437
whitslack pushed a commit to whitslack/lightning that referenced this issue Oct 28, 2022
@rustyrussell @whitslack
Makefile: replace mrkd with lowdown(1).
a4a1418 
Here's the before-vs-after comparison (ignoring whitespace changes):

```diff
 --- /tmp/before	2022-07-20 21:52:44.336641810 +0930
 +++ /tmp/after	2022-07-20 21:55:54.355487769 +0930
 @@ -1,7 +1,7 @@
 -LIGHTNING-CLI(1)                                          lightning-cli                                         LIGHTNING-CLI(1)
 +LIGHTNING-CLI(1)                                                                                                LIGHTNING-CLI(1)
  
  NAME
 -       lightning-cli - Control lightning daemon
 +       lightning-cli -- Control lightning daemon
  
  SYNOPSIS
         lightning-cli [OPTIONS] command
 @@ -14,10 +14,7 @@
  
          --conf=PATH Sets configuration file (default: lightning-dir/config ).
  
 -        --network=network
 -        --mainnet
 -        --testnet
 -        --signet Sets network explicitly.
 +       --network=network --mainnet --testnet --signet Sets network explicitly.
  
          --rpc-file=FILE Named pipe to use to talk to lightning daemon: default is lightning-rpc in the lightning directory.
  
 @@ -43,8 +40,8 @@
  
          --version/-V Print version number to standard output and exit.
  
 -        allow-deprecated-apis=BOOL  Enable  deprecated options. It defaults to true, but you should set it to false when testing
 -       to ensure that an upgrade won't break your configuration.
 +       allow-deprecated-apis=BOOL Enable deprecated options. It defaults to true, but you should set it to false when testing to
 +       ensure that an upgrade won't break your configuration.
  
  COMMANDS
         lightning-cli simply uses the JSON RPC interface to talk to lightningd, and prints the results. Thus the commands  avail‐
 @@ -67,7 +64,7 @@
  
         lightning-cli help
  
 -              1.     Fund a 10k sat channel using uncomfirmed outputs
 +       2.     Fund a 10k sat channel using uncomfirmed outputs
  
         lightning-cli --keywords fundchannel id=028f...ae7d amount=10000sat minconf=0
  
 @@ -84,4 +81,4 @@
         Note: the modules in the ccan/ directory have their own licenses, but the rest of the code is covered  by  the  BSD-style
         MIT license.
  
 -                                                                                                                LIGHTNING-CLI(1)
 +Core Lightning v0.11.0.1-350-gac2e137                                                                           LIGHTNING-CLI(1)
```

Signed-off-by: Rusty Russell <[email protected]>
Fixes: ElementsProject#5437
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees

@rustyrussell rustyrussell

Labels
docs
Projects
None yet
Milestone
v22.11
Development

No branches or pull requests
6 participants
@jb55 @wtogami @rustyrussell @whitslack @grubles @vincenzopalazzo