Results 1 to 10 of 10

Thread: Man pages are hideous at times...

  1. #1
    Join Date
    Jun 2011
    Location
    United Kingdom
    Beans
    Hidden!
    Distro
    Lubuntu Development Release

    Post Man pages are hideous at times...

    As I quite often use the:

    Code:
    man command
    command, I notice that many of the entries are:

    a) not newb-friendly
    b) not friendly (full stop)
    c) misleading
    d) Heavy and not useful because of that.

    I would very much like to help improve some of these manpages, but:

    1. How? I have tried a google search, but nothing.
    2. Is there a markup language or programming language I need to learn?
    3. Am I allowed to? Or is the manpage written by the dev only?
    4. Would a very user-friendly manual; i.e. extended to perhaps twice the length it needs to be for greater clarity be welcomed by the majority of users? Or would I be better writing some other form of documentation instead?

    No disservice to the devs, I program myself. Writing a README that doesn't irritate, but does provide clear instructions is a nightmare.
    Last edited by MG&TL; September 26th, 2011 at 11:55 PM.

  2. #2
    Join Date
    Jun 2011
    Location
    The Shadow Gallery
    Beans
    6,807

    Re: Man pages are hideous at times...

    Quote Originally Posted by MG&TL View Post
    As I quite often use the:

    Code:
    man command
    command, I notice that many of the entries are:

    a) not newb-friendly
    b) not friendly (full stop)
    c) misleading
    d) Heavy and not useful because of that.

    I would very much like to help improve some of these manpages, but:

    1. How? I have tried a google search, but nothing.
    2. Is there a markup language or programming language I need to learn?
    3. Am I allowed to? Or is the manpage written by the dev only?
    4. Would a very user-friendly manual; i.e. extended to perhaps twice the length it needs to be for greater clarity be welcomed by the majority of users? Or would I be better writing some other form of documentation instead?
    info command

    command --help

    are sometimes a bit better

    or you can use gmanedit to edit them

    http://www.ghacks.net/2010/06/04/edi...with-gmanedit/

    and some tips on man page writing and editing:

    http://linuxfocus.org/English/Novemb...ticle309.shtml
    Feel Free to Bitcoin Tip: 135Rp4pwwYTHEJ4u8bxKaDQiC91N9LUoV2

    Backtrack - Giving machine guns to monkeys since 2006
    Kali-Linux - Adding a grenade launcher to the machine guns since 2013

  3. #3
    Join Date
    Jun 2011
    Location
    United Kingdom
    Beans
    Hidden!
    Distro
    Lubuntu Development Release

    Re: Man pages are hideous at times...

    I realise about the alternatives; I just understand 'man' is the 'definitive guide' approach.

    ghacks link looks interesting. Thanks, haqking.

  4. #4
    Join Date
    Nov 2005
    Location
    Bordeaux, France
    Beans
    11,294
    Distro
    Ubuntu 12.04 Precise Pangolin

    Re: Man pages are hideous at times...

    man pages are not tutorials, they are not supposed to be "friendly".

  5. #5
    Join Date
    Mar 2009
    Location
    Buenos Aires, AR
    Beans
    2,325
    Distro
    Ubuntu

    Re: Man pages are hideous at times...

    ^ +1
    They are Developer/Hacker oriented.

  6. #6
    Join Date
    May 2007
    Location
    East Yorkshire, England
    Beans
    Hidden!

    Re: Man pages are hideous at times...

    Manpages are for brief, to the point, documentation. Info pages are for more lengthy documentation.
    Website | Blog | The Arch Hurd Project

    If you want to ask about something I posted, send a PM, as I don't watch many threads

  7. #7
    Join Date
    Mar 2010
    Location
    Norway
    Beans
    674

    Re: Man pages are hideous at times...

    Maybe you could create your own documentation project?

    You could have a wiki server running, so people could create simple documentation for how programs works, then you could create a command line tool that use this documentation.

  8. #8
    Join Date
    Jun 2011
    Location
    United Kingdom
    Beans
    Hidden!
    Distro
    Lubuntu Development Release

    Re: Man pages are hideous at times...

    Thanks for suggestions, guys. OK.

    wiki server's not within my capabilities, but I will know what to do next time if there's something very unclear or inaccurate.

    Thank you.

  9. #9
    Join Date
    May 2011
    Beans
    Hidden!

    Re: Man pages are hideous at times...

    If you think Ubuntu's man pages are evil, check out the Plan9's man page for emacs.

  10. #10
    Join Date
    Jun 2011
    Location
    United Kingdom
    Beans
    Hidden!
    Distro
    Lubuntu Development Release

    Re: Man pages are hideous at times...

    @BRRB That's....helpful.

    Bugs: Yes.

Tags for this Thread

Bookmarks

Posting Permissions

  • You may not post new threads
  • You may not post replies
  • You may not post attachments
  • You may not edit your posts
  •