Skip to content
Snippets Groups Projects

man: convert to reStructuredText

Merged Simon Ser requested to merge emersion/drm:rst into master
2 unresolved threads

I'm mostly opening this as an RFC to gather feedback. For now only one man page has been converted.

Signed-off-by: Simon Ser contact@emersion.fr

Edited by Simon Ser

Merge request reports

Loading
Loading

Activity

Filter activity
  • Approvals
  • Assignees & reviewers
  • Comments (from bots)
  • Comments (from users)
  • Commits & branches
  • Edits
  • Labels
  • Lock status
  • Mentions
  • Merge request status
  • Tracking
  • Fwiw I'm on board with this. There's been a few times when I wanted to improve the docs, with xml quickly convincing me otherwise.

    • Been meaning to do this since forever; thanks for doing it!

      If you convert them all (please do!), can I suggest an initial commit to put everything in place in meson but with an empty list, then one commit per page converted, and a final commit removing the leftover xml?

      You can already put my Acked-by: Eric Engestrom <eric@engestrom.ch> on all of those, and if you tag me on the MR I'll happily review each conversion :thumbsup:

    • Actually if you split the initial meson stuff into its own commit, that's already Reviewed-by: Eric Engestrom <eric@engestrom.ch>

    • Please register or sign in to reply
  • added docs label

    • Oh, another related thing, if you want to beat me to it: I've been meaning to look into the way the kerneldoc is hooked up and reproduce that here (and in mesa), so that we can have inline doc on interface functions that can be generated into html pages for the website :ok_hand:

    • Author Developer

      inline doc on interface functions that can be generated into html pages for the website

      Hm. I'd like to avoid having both man pages and inline docs for libdrm functions if possible. I wonder if we should remove the man pages altogether and replace them with regular rst pages.

    • Author Developer

      Don't get me wrong, I like man pages and would like to keep them if possible. I'd just prefer to avoid duplicating docs between the website, inline docs and man pages.

      I suppose all of this doesn't really affect this MR though. We'll want to write website docs in rst anyway, we'll be able to easily convert the man pages if necessary and/or move them to inline doc comments.

      Edited by Simon Ser
    • (I just realized I forgot to reply to this.)

      My point was that it would be good to generate both the man pages and website docs from inline docs, not to have yet another source of documentation.

      But you're right that this is orthogonal to this MR, I just mentioned it because you might be interested in that as well :)

    • Please register or sign in to reply
  • Simon Ser added 42 commits

    added 42 commits

    Compare with previous version

  • Simon Ser added 1 commit

    added 1 commit

    • 72027466 - man: convert to reStructuredText

    Compare with previous version

  • Simon Ser added 1 commit

    added 1 commit

    • ffba4d76 - man: convert to reStructuredText

    Compare with previous version

  • Author Developer

    Converted all man pages. This is ready for review.

  • Checked the meson & gitlab changes and spot-checked the new docs, and it looks good to me :thumbsup:

    Reviewed-by: Eric Engestrom <eric@engestrom.ch>

  • Simon Ser unmarked as a Work In Progress

    unmarked as a Work In Progress

  • Author Developer

    Gentle ping: should I do anything to get this merged?

  • Author Developer

    Bump

  • Simon Ser added 4 commits

    added 4 commits

    Compare with previous version

  • merged

Please register or sign in to reply
Loading