[TASK] Create a homepage for SSSD where we could link man pages

[sssd-bot]

Cloned from Pagure issue: https://pagure.io/SSSD/sssd/issue/3201

• Created at 2016-09-23 18:20:37 by jhrozek
• Closed at 2020-03-24 14:16:17 as wontfix
• Assigned to nobody

---

The SSSD man pages were written a long time ago when asciidoc or similar lightweight formats were not as widely used. But having the man pages in asciidoc or markdown would have the additional benefit of being able to render them directly in SCM browsers like github's without the need to convert them from XML to HTML during a release.

Comments

---

Comment from lslebodn at 2016-09-24 18:48:19

XML + dockbook has huge benefit => validation of man pages with DTD. We can generate markdown/asciidoc from xml.

cc: => lslebodn
resolution: => wontfix
status: new => closed

---

Comment from jhrozek at 2016-09-26 09:52:36

Please don't close RFEs without triage discussion in the future.

resolution: wontfix =>
status: closed => reopened

---

Comment from lslebodn at 2016-09-26 10:00:37

This one is not marked as RFE and it wasn't explain why it was re-opened. Closing again.

resolution: => wontfix
status: reopened => closed

---

Comment from jhrozek at 2016-09-26 10:07:15

It had type=enhancement.

Also, this is the discussion this ticket captures:

13:38 < spbnick> I volunteer for executing the conversion. I did similar thing for the DIGImend website (it was on MediaWiki) and it worked out quite well, although it was quite a bit more complicated than just 
a couple pages.
13:43 < sgallagh> spbnick: That's an interesting idea. If we were going to do that, it would be kind of excellent if we did the manpages as well into something like the ronn markdown format instead of the clumsy
 docbook XML.
13:45 < spbnick> sgallagh: Hmm, perhaps, can't say much about that - haven't had much experience with markdown for man pages.
13:45 < sgallagh> spbnick: https://rtomayko.github.io/ronn/ronn.1.html
13:46 < sgallagh> /me thinks it would save effort compared to having jhrozek-pto manually host the generated manpages for each release
13:49 < spbnick> sgallagh: Looks interesting, will keep it in mind, but I'm unfamiliar with Jakub's efforts on hosting manpages.
13:49 < sgallagh> spbnick: It's not complicated. After the build, he takes the .html files and sticks them in his fedorapeople.org space and adds a link to them in the Wiki
13:50 < sgallagh> But I think it would be really handy if that information was just trivially viewable in the code browser
13:50 < sgallagh> Not urgent, but nice to have
13:51 < spbnick> sgallagh: Argh. OK, I see. Yeah, something more readable than XML would be good. I don't expect GitHub or Pagure to render Markdown-based webpages very well, but we can try it.
13:52 < spbnick> sgallagh: *manpages
13:52 < sgallagh> /me shrugs. Probably worth a PoC in a personal fork, I'd think.

But most importantly, the triage is the only place where everyone can voice their opinion. Closing ticket without triage doesn't give other developers even a chance to say anything about the tickets. It's really not nice towards the rest of the team to close tickets without letting them go through triage.

resolution: wontfix =>
status: closed => reopened
summary: Convert SSSD man pages from XML to asciidoc or markdown or another modern format => [RFE] Convert SSSD man pages from XML to asciidoc or markdown or another modern format

---

Comment from jhrozek at 2016-09-26 10:21:20

btw good point about validation. But the most important part is that currently reading our man pages online sucks. We have the manpages on my personal fedoraproject account, which is not visible, google doesn't search that place well etc.

So if the result of this ticket is we keep the manpages in XML but we come up with a hosting space for SSSD (something simple like cmocka.org) that is not tied to my fedorapeople HTML dump, but tied to sssd as a project, I'll be equally happy. Then we could add a README.md file to the manpage directory telling people to go look to XYZ for manpages.

---

Comment from lslebodn at 2016-09-26 10:31:45

Replying to [comment:5 jhrozek]:

btw good point about validation. But the most important part is that currently reading our man pages online sucks. We have the manpages on my personal fedoraproject account, which is not visible, google doesn't search that place well etc.

Online reading of manual page sucks in general. The google does not know which version of sssd user has.
And google usually finds the latest version.

The very nice example is man sssd-sudo. Different version of sssd requires different configuration. And if users rely on information from the latest online documentation then it will not work.

So if the result of this ticket is we keep the manpages in XML but we come up with a hosting space for SSSD (something simple like cmocka.org) that is not tied to my fedorapeople HTML dump, but tied to sssd as a project, I'll be equally happy. Then we could add a README.md file to the manpage directory telling people to go look to XYZ for manpages.
It is not a bad idea; openshift might works.

---

Comment from jhrozek at 2016-09-26 11:01:50

Online reading of manual page sucks in general. The google does not know which version of sssd user has.

I totally agree, but for better or worse, that's what users do these days.

And google usually finds the latest version.

No, it's worse, google usually finds linux.die.net which is horribly outdated..

---

Comment from lslebodn at 2016-09-28 19:30:16

Replying to [comment:7 jhrozek]:

And google usually finds the latest version.

No, it's worse, google usually finds linux.die.net which is horribly outdated..
man pages in asciidoc or markdown does not guarantee higher rank then man pages on linux.die.net.

---

Comment from jhrozek at 2016-09-29 16:21:34

Fields changed

milestone: NEEDS_TRIAGE => SSSD Deferred
summary: [RFE] Convert SSSD man pages from XML to asciidoc or markdown or another modern format => [TASK] Create a homepage for SSSD where we could link man pages
type: enhancement => task

---

Comment from jhrozek at 2016-09-29 16:59:47

Fields changed

rhbz: => 0

---

Comment from jhrozek at 2017-02-24 14:22:44

Metadata Update from @jhrozek:

• Issue set to the milestone: SSSD Patches welcome

---

Comment from pbrezina at 2020-03-24 14:16:16

Thank you for taking time to submit this request for SSSD. Unfortunately this issue was not given priority and the team lacks the capacity to work on it at this time.

Given that we are unable to fulfill this request I am closing the issue as wontfix.

If the issue still persist on recent SSSD you can request re-consideration of this decision by reopening this issue. Please provide additional technical details about its importance to you.

Thank you for understanding.

---

Comment from pbrezina at 2020-03-24 14:16:18

Metadata Update from @pbrezina:

• Issue close_status updated to: wontfix
• Issue status updated to: Closed (was: Open)