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

Add support for manpages via mandoc #1196

Closed
wants to merge 22 commits into from
Closed

Add support for manpages via mandoc #1196

Show file tree
Hide file tree
Changes from 5 commits
Commits
Show all changes
22 commits
Select commit Hold shift + click to select a range
2008073
Initial try at adding manpage support via mandoc
dctucker May 8, 2018
d6643c3
adding xslt transformation
dctucker May 9, 2018
3deeea0
stripping html/body, non-linked h1, ltitle formatted
dctucker May 9, 2018
f149841
Incorporate feedback, hook into testing
Oct 30, 2018
f00e30c
Forgot new test fixtures
Oct 30, 2018
19abce5
Regenerate test fixture with latest mandoc
Oct 31, 2018
da73a08
Add new dependencies to Travis
Oct 31, 2018
11c43b4
Support man pages in section 0 if they have a suffix
Oct 31, 2018
786e531
Deal with html-pipeline stripping our styling
Oct 31, 2018
521ccf9
Fix up tests
Oct 31, 2018
a43da81
Near-final tweaks
Oct 31, 2018
1b6203f
Fix content of text artifacts to match actual filename
Nov 1, 2018
a190353
Add line about mdoc/man support to README.md
Nov 1, 2018
52b32d7
Add note about mandoc version to xslt
Nov 1, 2018
b32d9de
Update lib/github/markups.rb
Alhadis Nov 6, 2018
fb06417
Resolve merge conflicts with 'master' branch
Alhadis Oct 23, 2020
333ccfc
Use portable interpreter directives
Alhadis Oct 23, 2020
6b078bb
Limit rendering to "Roff Manpage" files only
Alhadis Oct 23, 2020
cb28ead
Finish off XSLT
Alhadis Oct 24, 2020
5df53fa
Use squiggly heredoc syntax
Alhadis Oct 24, 2020
2bde37d
Update fixture
Alhadis Oct 24, 2020
88678cd
Remove stupid test that's failing for zero reason
Alhadis Oct 24, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
2 changes: 1 addition & 1 deletion lib/github-markup.rb
View file
Open in desktop
@@ -1,6 +1,6 @@
module GitHub
module Markup
VERSION = '3.0.1'
VERSION = '3.0.2'
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Not sure if this is appropriate to do here or if we want to roll out a release as a separate PR. Might also be worth more than a patch version; maybe 3.1.0? cc @kivikakk @lildude

Version = VERSION
end
end
3 changes: 3 additions & 0 deletions lib/github/commands/man2html
View file
Open in desktop
@@ -0,0 +1,3 @@
#!/bin/sh
mandoc -Thtml -Ofragment "$@" \
| xmlstarlet tr --html "$(dirname "$0")/man2html.xslt" -
69 changes: 69 additions & 0 deletions lib/github/commands/man2html.xslt
View file
Open in desktop
@@ -0,0 +1,69 @@
<?xml version="1.0" encoding="utf-8"?>
<xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
<!-- Default: match anything and apply templates to it -->
<xsl:template match="node()|@*">
<xsl:copy>
<xsl:apply-templates select="node()|@*"/>
</xsl:copy>
</xsl:template>

<!-- Turn these into breaks -->
<xsl:template match="div[@class='Pp']">
<br/><br/>
</xsl:template>

<!-- Headers don't need to be linking to themselves -->
<xsl:template match="a[@class='permalink']">
<xsl:copy-of select="text()"></xsl:copy-of>
</xsl:template>

<!-- The rest is ported styles from mandoc default CSS -->
<xsl:template match="table[@class='head']|table[@class='foot']">
<xsl:copy>
<xsl:attribute name="style">width: 100%;</xsl:attribute>
<xsl:apply-templates />
</xsl:copy>
</xsl:template>

<xsl:template match="td[@class='head-rtitle']|td[@class='foot-os']">
<xsl:copy>
<xsl:attribute name="style">text-align: right;</xsl:attribute>
<xsl:apply-templates />
</xsl:copy>
</xsl:template>

<xsl:template match="td[@class='head-vol']">
<xsl:copy>
<xsl:attribute name="style">text-align: center;</xsl:attribute>
<xsl:apply-templates />
</xsl:copy>
</xsl:template>

<xsl:template match="div[@class='Nd']|div[@class='Bf']|div[@class='Op']">
<xsl:copy>
<xsl:attribute name="style">display: inline;</xsl:attribute>
<xsl:apply-templates />
</xsl:copy>
</xsl:template>

<xsl:template match="span[@class='Pa']|span[@class='Ad']">
<xsl:copy>
<xsl:attribute name="style">font-style: italic;</xsl:attribute>
<xsl:apply-templates />
</xsl:copy>
</xsl:template>

<xsl:template match="span[@class='Ms']|dl[@class='BL-diag']/dt">
<xsl:copy>
<xsl:attribute name="style">font-weight: bold;</xsl:attribute>
<xsl:apply-templates />
</xsl:copy>
</xsl:template>

<xsl:template match="code[@class='Nm']|code[@class='Fl']|code[@class='Cm']|code[@class='Ic']|code[@class='In']|code[@class='Fd']|code[@class='Fn']|code[@class='Cd']">
<xsl:copy>
<xsl:attribute name="style">font-weight: bold; font-family: inherit;</xsl:attribute>
<xsl:apply-templates />
</xsl:copy>
</xsl:template>
</xsl:stylesheet>
1 change: 1 addition & 0 deletions lib/github/markup.rb
View file
Open in desktop
Expand Up @@ -19,6 +19,7 @@ module Markups
MARKUP_RDOC = :rdoc
MARKUP_RST = :rst
MARKUP_TEXTILE = :textile
MARKUP_MANPAGE = :manpage
end

module Markup
Expand Down
2 changes: 2 additions & 0 deletions lib/github/markups.rb
View file
Open in desktop
Expand Up @@ -52,3 +52,5 @@
)

command(::GitHub::Markups::MARKUP_POD, :pod2html, /pod/, ["Pod"], "pod")

command(::GitHub::Markups::MARKUP_MANPAGE, :man2html, /([1-9n][a-z]*|man|mdoc)(\.in)?/, ["Roff"], "manpage")
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If man pages in section 0, e.g. the POSIX string.h(0p), aren't going to be supported then can that please be stated so I can stop pointing out the regexp doesn't permit them.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Maybe I misunderstood; I thought that pages in section 0 were plain-text and thus did not require formatting?

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Nope.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@Alhadis Is that just 0p then, or should I treat 0 as any other section? I swore someone told me the .0 files were pre-formatted...

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

see @ischwarze comment #1196 (comment)

*.0 -- those are preformatted manual pages, essentially *.txt files; consequently, they rarely occur in source trees, but still, manual page formatters cannot handle them, you simply read them with a pager like more(1) or less(1)

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I've added 0[a-z]+ to the regex; hopefully that's an acceptable compromise.

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yep. Sometimes called "catman pages", after the catman(1) program which generates preformatted output for terminal display. So named because you could run cat on its output to see the formatted manpage.

The program was really only relevant in the old days when processors were limited in their power, and formatting a man-page was a potentially costly procedure.

Nowadays, processors are so powerful we hardly notice the time spent formatting the Roff markup, and having catman pages lingering around can actually be problematic if the manpage's source is needed...

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Perhaps @ischwarze can clarify where they occur when he has the time. I've not noticed a `.0' suffix being used for catman pages. catman(8) here says, regarding the sections to search, ‘The default is "1 n l 8 3 0 2 5 4 9 6 7"’, note the 0, and so man-db, where it's from, doesn't require a letter suffix and treats 0 as just another section for source needing formatting.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Erf, didn't mean to comment twice; I'll leave it as until @ischwarze can weigh in but based on catman(8) I'm leaning towards just treating .0 as a regular section instead of special casing it like it is now

5 changes: 3 additions & 2 deletions test/markup_test.rb
View file
Open in desktop
Expand Up @@ -74,7 +74,7 @@ def call
message
end
end

def test_knows_what_it_can_and_cannot_render
assert_equal false, GitHub::Markup.can_render?('README.html', '<h1>Title</h1>')
assert_equal true, GitHub::Markup.can_render?('README.markdown', '=== Title')
Expand All @@ -92,8 +92,9 @@ def test_each_render_has_a_name
assert_equal "asciidoctor", GitHub::Markup.renderer('README.adoc', '== Title').name
assert_equal "restructuredtext", GitHub::Markup.renderer('README.rst', 'Title').name
assert_equal "pod", GitHub::Markup.renderer('README.pod', '=begin').name
assert_equal "manpage", GitHub::Markup.renderer('README.mdoc', '.Dd $Mdocdate: March 23 1981 $').name
end

def test_rendering_by_symbol
assert_equal '<p><code>test</code></p>', GitHub::Markup.render_s(GitHub::Markups::MARKUP_MARKDOWN, '`test`').strip
end
Expand Down
6 changes: 6 additions & 0 deletions test/markups/README.mdoc
View file
Open in desktop
@@ -0,0 +1,6 @@
.Dd $Mdocdate: March 23 1981 $
.Dt README 1
.Os GitHub
.Sh README.mdoc
.Nm README
.Nd This is an example readme in mandoc
20 changes: 20 additions & 0 deletions test/markups/README.mdoc.html
View file
Open in desktop
@@ -0,0 +1,20 @@
<html><body>
<table style="width: 100%;">
<tr>
<td class="head-ltitle">README(1)</td>
<td style="text-align: center;">General Commands Manual</td>
<td style="text-align: right;">README(1)</td>
</tr>
</table>
<div class="manual-text">
<h1 class="Sh" title="Sh" id="README.mdoc"><a class="selflink" href="#README.mdoc">README.mdoc</a></h1>
jordemort marked this conversation as resolved.
Show resolved Hide resolved
<b class="Nm" title="Nm">README</b> — <span class="Nd" title="Nd">This is
an example readme in mandoc</span>
</div>
<table style="width: 100%;">
<tr>
<td class="foot-date">March 23, 1981</td>
<td style="text-align: right;">GitHub</td>
</tr>
</table>
</body></html>