Docs: Man pages for CLI commands

[omajid]

The dotnet/cli repo contains bunch of documentation that includes man pages for the cli tooling (such as dotnet publish). Unfortunately, those are not very well maintained - the current docs still refer to project.json! See https://github.com/dotnet/cli/issues/7291 for more background.

I noticed that this repo contains documentation that appears on https://docs.microsoft.com/, such as https://docs.microsoft.com/en-us/dotnet/core/tools/dotnet-publish. These tool docs look very, very close to man pages. And unlike the cli docs, these are well maintained.

Would it be possible to generate man pages from these docs? I can help out with implementing this if this idea seems sensible.

[mairaw]

@nguerrera @livarcocc @richlander Z used to generate the man pages from our docs in the past, but I thought the process had changed since then?

[omajid]

It looks like no one picked up that task when Z left. As I see it, there is no process currently :(

[nguerrera]

@omajid is right. We need to figure out the best way to get the man pages to sync directly from the docs.microsoft.com content. Any manual steps will just risk us getting back to this bad state in the future.

[omajid]

It looks like pandoc can generate man pages from existing docs already.

pandoc -s -f markdown -t man -o dotnet.1 docs/core/tools/dotnet.md
man ./dotnet.1

The generated docs do need some cleanup, though. Here is a quick list of issues from running the commands above:

• No section name in man page docs
  
  
  
  • Edit: Can fix this by adding section: 1 variable to markdown files.
  
  
• Section names are not consistent with other programs (Name vs NAME)
• Option names/descriptions are not indented correctly. Also a problem for examples and environment variables
  
  
  
  • Edit: fixing this requires pandoc-specific markup
  
  
• Tables are completely messed up
• Links to other documents in docs are completely messed up

[omajid]

Ping. Anyone have any thoughts on how to proceed from here?

[omajid]

Ping. I would appreciate some guidance on what a new man page workflow should be.

[omajid]

Sorry for making noise, but I would appreciate some comments and/or suggestions on how to proceed.

[nguerrera]

Thanks for pushing on this, @omajid. I'm sorry for not responding sooner.

Adding @KathleenDollard, our new PM, for her thoughts too.

I'm now thinking that it is going to be tough to implement this in a way that is fully automated and does not interfere with the daily flow of documentation writers or CLI developers.

Also, we only got feedback (that I saw) about the bad man pages on the verge of 2.0 RTM and yet they are all about project.json! This makes me wonder if folks are even finding the man pages. I didn't even know they existed until this was raised as they were never updated during any of my time on the team.

Initially, I think we should just delete the bad man pages or just have man dotnet with a basic description and a pointer to dotnet help that can launch the up-to-date docs in a browser.

[omajid]

I'm now thinking that it is going to be tough to implement this in a way that is fully automated and does not interfere with the daily flow of documentation writers or CLI developers.

Maybe we can handle it async a couple of times every release cycle? In other words, at some point a developer (say, me) can get a heads up from doc folks that the general docs are complete and the dev can sync them?

Also, we only got feedback (that I saw) about the bad man pages on the verge of 2.0 RTM and yet they are all about project.json! This makes me wonder if folks are even finding the man pages. I didn't even know they existed until this was raised as they were never updated during any of my time on the team.

This might be a chicken and egg problem. I don't think Microsoft binaries include them. I looked through https://www.microsoft.com/net/core#linuxfedora for example and only dotnet.1 is included there. I know all man pages are included in RHEL RPMs and community Fedora RPMs (only because I found them and added them).

Initially, I think we should just delete the bad man pages or just have man dotnet with a basic description and a pointer to dotnet help that can launch the up-to-date docs in a browser.

Some distributions, like Debian, consider it a bug if man pages are missing. I would strongly consider keeping them unless there is a very good reason not to.

[svick]

@nguerrera

I think man pages become more important once .Net Core becomes part of package repositories of distributions.

Right now, to install .Net Core, I have to find a guide like https://www.microsoft.com/net/core#linuxubuntu, which can direct me to the documentation. It also means I have used the browser recently, so I might use it again when looking for documentation.

But once I can just do something like sudo apt install dotnet, then I think man dotnet is an obvious next step, especially since I used only shell and I might not even have a browser open.

[KathleenDollard]

My thoughts?

We should do this.

What? Still working on. Have a call to my favorite Linux folks later today.

At least ifno on the level of –help, which is also on my radar to see improved, and a docs link.

We’re cross platform as an org. I’ll work with docs to see what they think that should mean.

Kathleen

From: Nick Guerrera [mailto:[email protected]]
Sent: Wednesday, August 30, 2017 7:53 AM
To: dotnet/docs [e-mail]
Cc: KathleenDollard [e-mail]; Mention [e-mail]
Subject: Re: [dotnet/docs] Man pages for CLI commands (#2791)

Thanks for pushing on this, @omajid https://github.com/omajid . I'm sorry for not responding sooner.

Adding @KathleenDollard https://github.com/kathleendollard , our new PM, for her thoughts too.

I'm now thinking that it is going to be tough to implement this in a way that is fully automated and does not interfere with the daily flow of documentation writers or CLI developers.

Also, we only got feedback (that I saw) about the bad man pages on the verge of 2.0 RTM and yet they are all about project.json! This makes me wonder if folks are even finding the man pages. I didn't even know they existed until this was raised as they were never updated during any of my time on the team.

Initially, I think we should just delete the bad man pages or just have man dotnet with a basic description and a pointer to dotnet help that can launch the up-to-date docs in a browser.

—
You are receiving this because you were mentioned.
Reply to this email directly, view it on GitHub https://github.com/dotnet/docs/issues/2791#issuecomment-326015911 , or mute the thread https://github.com/notifications/unsubscribe-auth/AFktXgyspaIBham8CteFUb0_udkgNUaqks5sdXdQgaJpZM4Oox6h . https://github.com/notifications/beacon/AFktXkor59D2Fs7N4wkFI_TbWgYTZMcvks5sdXdQgaJpZM4Oox6h.gif

[omajid]

Hi @KathleenDollard , any updates on this? Is there anything I can help with?

[omajid]

Ping. Just trying to make sure we come to a decision and implement it!

[omajid]

Ping. Has anyone given this any thought?

[livarcocc]

We haven't given any extra thought on this yet. My main point is that this needs to be automatic somehow, otherwise it will just go out of sync completely again.

[omajid]

Please let me know how I can help in addressing this.

[ghost]

It looks like pandoc can generate man pages from existing docs already.
pandoc -s -f markdown -t man -o dotnet.1 docs/core/tools/dotnet.md man ./dotnet.1

Seems like the CI script that runs pandoc command is not open sourced.. can one of the admin update the script with the proposed parameters and see the impact?

My main point is that this needs to be automatic

Seems like it's already automatic. All these docs are generapted by pandoc util https://github.com/search?q=org%3Adotnet+pandoc&type=Code but the caller script is not in open.. maybe it belongs to dotnet/core-eng private repo?

[omajid]

@kasper3 It seems this was never part of CI. Someone used to run it manually and the process broke when they left. See https://github.com/dotnet/cli/issues/7291#issuecomment-318507252 for the additional context.

[mairaw]

Given that we have #7291 tracking this issue, is it ok to close this one? They seem duplicate to me.

[mairaw]

I'm closing this one given that we have issue https://github.com/dotnet/cli/issues/7291 tracking this work. I'm not aware of any work items for the docs team re. man pages at the moment.

/cc @livarcocc @KathleenDollard

[omajid]

Would it be possible to keep this open? I agree that there is no well defined work at the moment and docs team may not be responsible for this, but having severely out of date man pages is an issue and it needs to be (somehow) addressed.

[ghost]

@mairaw, @mmitche, can dotnet-bot send followup PRs to dotnet/docs repos after something is merged by contributors?

The packaging team can then pick up the manpage changes. With all the cool features @dotnet-bot is bringing via https://github.com/dotnet/dotnet-ci, this seems like a very simple / low-cost thing with huge advantage for Unix consumers.

Using PowerShell:

$pandocVersion = "2.1.3"
$pandocVersionedName = "pandoc-$pandocVersion"
$pandoc = "C:\$pandocVersionedName\pandoc.exe"

# caching, so we don't have to download pandoc again
if (!(Test-Path $pandoc)) {
  [Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12

  Invoke-WebRequest -OutFile  "$pandocVersionedName.zip" `
    https://github.com/jgm/pandoc/releases/download/$pandocVersion/$pandocVersionedName-windows.zip

  Expand-Archive "$pandocVersionedName.zip" -DestinationPath c:\
  Remove-Item "$pandocVersionedName.zip"
}

ls docs\core\tools\dotnet*.md | foreach {
  $mdFile = $_
  $manFile = [io.path]::ChangeExtension($mdFile, '1')

  echo "working on $mdFile"

  &$pandoc -s -t man "$mdFile" -o "$manFile"
}