mle86 / man-to-md Goto Github PK

Bold and italic blocks started with \fB or \fI may be ended with \fP as well (not just \fR).
I did the following patch:

381,382c381,382
<       s/\\fB([^\*_]|.{2,}?)\\fR/**$1**/g;
<       s/\\fI([^\*_]|.{2,}?)\\fR/_$1_/g;
---
>       s/\\fB([^\*_]|.{2,}?)\\f[RP]/**$1**/g;
>       s/\\fI([^\*_]|.{2,}?)\\f[RP]/_$1_/g;
399,400c399,400
<       s#\\fB(\*|_)\\fR#<b>\\$1</b>#g;
<       s#\\fI(\*|_)\\fR#<i>\\$1</i>#g;
---
>       s#\\fB(\*|_)\\f[RP]#<b>\\$1</b>#g;
>       s#\\fI(\*|_)\\f[RP]#<i>\\$1</i>#g;
465,466c465,466
<       s#\\fB(.+?)\\fR#<b>$1</b>#g;
<       s#\\fI(.+?)\\fR#<i>$1</i>#g;
---
>       s#\\fB(.+?)\\f[RP]#<b>$1</b>#g;
>       s#\\fI(.+?)\\f[RP]#<i>$1</i>#g;

most common markdown renderers i'm familiar with automatically create anchors for # headers. there's no need to generate <a name=...> tags for them.

Hi!
I'm receiving the following error when trying to convert nvim man page to markdown.

perl man-to-md.pl < $(man --where --all nvim) > nvim.md
could not parse first line at man-to-md.pl line 575, <> line 1.

These are thef first lines of Nvim man page.

.Dd December 17, 2017
.Dt NVIM 1
.Os
.Sh NAME
.Nm nvim
.Nd edit text
.Sh SYNOPSIS
.Nm
.Op Ar options
.Op Ar file ...

I tried converting one of my system's manpages with man-to-md and it looked fine in a standalone markdown viewer:

When strip is used with no options on an executable file, it checks that file to see if it uses the dynamic link editor. If it does, the effect of the strip command is the same as using the -u and -r options. If the file does not use the dynamic link editor, the effect of strip without any options is the same as using the -s option of ld(1). The options -S, -x, and -X have the same effect as the ld(1) options. The options to strip(1) can be combined to trim the symbol table to just what is desired.

But when I pasted the generated markdown into a GitHub issue, there were a lot of unnecessary extra linebreaks:

When
strip
is used with no options on an executable file, it checks that file to see if it uses the dynamic link editor.
If it does, the effect of the
strip
command is the same as using the
-u
and
-r
options. If the file does not use the dynamic link editor, the effect of
strip
without any options is the same as using the
-s
option of
ld(1).
The options
-S,
-x,
and
-X
have the same effect as the
ld(1)
options.
The options to
strip(1)
can be combined to trim the symbol table to just what is desired.

Could man-to-md better support GitHub Flavored Markdown?

the .nf and .fi macros are used to force newlines to be retained. it's quite handy for creating a flat list, or for code snippets.
https://www.gnu.org/software/groff/manual/html_node/Manipulating-Filling-and-Adjusting.html

the perl script oddly indents the code instead. i guess it's going for automatic code mode or something ?

example input:

.nf
One item.
Another item.
.fi

a reasonable md rendering would be to just add <br> to the end of each line i think:

One item.<br>
Another item.<br>

The latest release of this project is 0.14.1 but newer versions up to 0.17.0 have been tagged. Should releases be created for those newer tags, or are versions after 0.14.1 not considered to be usable releases?

unescaped - run the risk of being automatically converted to other characters in outputs depending on what follows it. -- is commonly converted to an – (U+2013 endash). this is undesirable for code documentation like command line options as they no longer can be copied & pasted. that's why man pages will often write \-\-foo for the --foo command line option.

depending on the renderer, markdown has this feature as well -- it creates endashes whenever it sees --. this def happens on github pages for example.

the current man-to-md script will strip away the \ from something like \-\-foo yielding --foo which turns into –foo which is not good :).

i think just leaving \- as \- should be fine for most markdown renderers ?

I gave a try to man-to-md, while I can successfully use it on the samples from test/samples/
directory, when trying to convert any standard man page from my linux system (like man.1 or ls.1) give an error:

 could not parse first line at man-to-md/man-to-md.pl line 413, <> line 1.

What is wrong with the roff format of standard manuals?

It also fails on a simple example like foo.1 from the Linux Man Page Howto.

λ man2md ls
/usr/share/man/man1/ls.1
could not parse first line at /Users/storm/bin/man2md.pl line 626, <> line 38.

λ man2md which
/usr/share/man/man1/which.1
could not parse first line at /Users/storm/bin/man2md.pl line 626, <> line 32.

λ man2md systemsetup
/usr/share/man/man8/systemsetup.8
could not parse first line at /Users/storm/bin/man2md.pl line 626, <> line 18.

λ uname -a
Darwin 10core.local 19.4.0 Darwin Kernel Version 19.4.0: Wed Mar  4 22:28:40 PST 2020; root:xnu-6153.101.6~15/RELEASE_X86_64 x86_64

I was so happy when I found this project.
Using it to pass its output to Cobertos/md2notion project, to archive man-pages and then edit them, then to recall I use the wrjlewis/notion-search-alfred-workflow project to search Notion for the edited man-page. But, most of the manual pages I wanted to archive, throws an error as the above. Is this related to #5 perhaps? Since it errors out on most everything I wanted to convert perhaps this is something different? I do not know perl that well, nor the *roff formats, how would we proceed to get this fixed?

This file is not converted with the latest man-to-md.pl.

SCI_Bcast.3.txt

Thank you for this very useful project. Converting one of my man pages, I noticed that a \(co which man displays as ©, stays an escaped sequence. I think man-to-md should also do the conversion.

when coverting from .roff to .md, "<" becomes "&lt;"

the script requires .TH provide 4 arguments, but only 2 are required. the spec for .TH:

https://www.gnu.org/software/groff/manual/html_node/Man-usage.html
Macro: .TH title section [extra1 [extra2 [extra3]]]

otherwise the script fails with could not parse first line