mle86 / man-to-md Goto Github PK
View Code? Open in Web Editor NEWConverts man pages to Markdown
License: GNU General Public License v3.0
Converts man pages to Markdown
License: GNU General Public License v3.0
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 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?
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 ...
most common markdown renderers i'm familiar with automatically create anchors for #
headers. there's no need to generate <a name=...>
tags for them.
This file is not converted with the latest man-to-md.pl
.
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>
λ 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?
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?
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;
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.
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.
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
when coverting from .roff
to .md
, "<" becomes "<"
A declarative, efficient, and flexible JavaScript library for building user interfaces.
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
An Open Source Machine Learning Framework for Everyone
The Web framework for perfectionists with deadlines.
A PHP framework for web artisans
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
Some thing interesting about web. New door for the world.
A server is a program made to process requests and deliver data to clients.
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
Some thing interesting about visualization, use data art
Some thing interesting about game, make everyone happy.
We are working to build community through open source technology. NB: members must have two-factor auth.
Open source projects and samples from Microsoft.
Google ❤️ Open Source for everyone.
Alibaba Open Source for everyone
Data-Driven Documents codes.
China tencent open source team.