Update dotnet manpages for Unix

[ghost]

skip ci please

[ghost]

@omajid, @nguerrera, @mmitche fyi

[ghost]

Seems like "skip ci please" from PR instructions has no effect 🙈

[nguerrera]

Were you able to launch these new man pages and confirm that they look good?

Was there no manual fixup needed?

[nguerrera]

Thank you for providing the steps used.

[omajid]

This is awesome! 👍

I ran

• wget https://raw.githubusercontent.com/kasper3/cli/0177a2156cff54220aa5269bcd0a8cb891a35d5c/Documentation/manpages/sdk/dotnet.1
• man ./dotnet.1

I think we need some pre-processing of the .md files or post-processing of man pages.

[omajid]

ls docs-master/docs/core/tools/dotnet*.md | while read -r line; do pandoc -t man "$line" -o "$(basename ${line%.md}.1)"; done

Can you add a -s to the pandoc invocation?

Edit: Here is how it looks after the -s on my system:

Some things that still look wrong:

• Missing section number. -V section=1 to pandoc will fix this.
• [!INCLUDE garbage. I have a python filter to use with pandoc to remove this.
• We need a way to filter to just the .NET Core 2.x (#tab/netcore2x) section, instead of having both 2.x and 1.x in man pages (right?)
• tables are messed up. It appears --column=2000 (or any large-ish value) fixes this. Not sure how correct this is.
• Section names are not capitalized.
• references and links are still broken - they appear as the filename.

[ghost]

@omajid fixed. I checked man ./dotnet.1 and it looks fine.

[ghost]

(also updated the bash script in top post and powershell script in comment with -s option)

[ghost]

For the formatting issues, should we instead try fixing them or reporting them upstream: https://github.com/jgm/pandoc to make most profit for world (instead of manual fixes)?

[ghost]

Pandoc seems to have extension points using custom filters http://pandoc.org/filters.html, that can be written in ruby, perl or python and use it as pandoc -F ./myhandler -t man dotnet.md -o dotnet.1. .NET binding project seem quite old https://github.com/t0yv0/libpandoc-dotnet.

[nguerrera]

For 2.1, maybe we just fix up the formatting manually? Pains me to say that, but I don't want this to derail into getting nothing done for 2.1.

[omajid]

After playing around a bit, I think I have something decent working, without any manual modifications (but see the filter file below).

This what man ./dotnet.1 now looks like:

This is the command I used to generate the man pages:

ls docs-master/docs/core/tools/dotnet*.md | while read -r line; do pandoc -s -t man -V section=1 -V header=".NET Core" --column=500 --filter man-pandoc-filter "$line" -o "$(basename ${line%.md}.1)"; done

I know the column value looks very wrong, but the tables are wrapped around fairly well with this. I tried various terminal widths and it doesn't look terrible on any width I could find. It's not perfect, but much better than not having a large column value.

The filter file (a giant hack!) is: https://gist.github.com/omajid/22c4bbfdd6a8e235b2248f168f8523d0

This was done with:

$ pandoc --version
pandoc 1.19.1
Compiled with pandoc-types 1.17.0.5, texmath 0.9.1, highlighting-kate 0.6.4
Default user data directory: /home/omajid/.pandoc
Copyright (C) 2006-2016 John MacFarlane
Web: http://pandoc.org
This is free software; see the source for copying conditions.
There is no warranty, not even for merchantability or fitness
for a particular purpose.
$ rpm -q python3-pandocfilters
python3-pandocfilters-1.4.1-2.fc27.noarch

[ghost]

@nguerrera, my two cents: merge this PR as these files were last updated two years ago, so this changeset is already much better than what we have in master. Subsequent improvements can be done in follow up PRs and we can think of how to automate this process in #7291.

[nguerrera]

I might have been convinced but @omajid's pages look so nice. 😁

Here's what I'd like:

1. Commit that gist along with an update-man-pages.sh that repeats the whole generation.

2. Use update-man-pages.sh to regenerate the files.

3. Commit the updated files.

Can you do that? I'd say we can last several releases if we're down to one button to update the man pages with a script.

Thanks so much to both of you for pushing on this!

[omajid]

@kasper3 feel free to update this PR and include the filter file. Could you please add a .NET Foundation license header to it as well?

[ghost]

@omajid, thanks for the filter script.

@nguerrera, I have added tool scripts in a separate directory and update the docs. There is a readme in tools dir with usage example https://github.com/dotnet/cli/blob/ee24d81648b6792c7249c5044f6218f59b89e49c/Documentation/manpages/tool

[nguerrera]

Thanks!

[ghost]

$ pandoc --version
pandoc 1.19.1

@omajid, a lot has improved in their core since then. I have updated readme with note to promote using latest version of pandoc under Ubuntu example, how to quickly install it from packages available for different distros at https://github.com/jgm/pandoc/releases.

For other distros, it can be built using tarball https://github.com/jgm/pandoc/blob/master/INSTALL.md#linux.

[omajid]

a lot has improved in their core since then.

That's a good point. In fact, looking at the release notes, it seems like one of the issues I was seeing (bad links) was fixed in 2.0.5: "omit internal links (#4136). That is, just print the link text without the URL.".

And thanks again everyone for getting this resolved before 2.1!