docs?

tam1138 · 2007-11-17 05:32:22

Why is the lack of documentation endemic to Arch packages? I can sort of understand why fancy html docs are not included, but man pages?! Honestly! Whiskey tango foxtrot?

I've already filed a few bugs requesting re-addition of documentation to specific packages, but this problem is widespread enough that it deserves attention at a higher level. I would really like to see it dealt with. At least provide the option of including documentation somehow. It's almost certainly too much of a pain to maintain a parallel set of packages including documentation; is it a repo bandwidth problem? It can't possibly be a user disk space problem.

Seriously, I'd like to know why this is an unspoken part of The Arch Way and then I'd like it fixed, because it's Wrong. I will be happy to provide lists of offending packages, patches, or---God forbid you let me loose in CVS---commit the bloody things myself.

DonVla · 2007-11-17 05:39:17

imo unnecessary. for html docs ask the allmighty internet. man ... is sufficient and faster than searching some html pages under /usr/share/...

vlad

EDIT:

I can sort of understand why fancy html docs are not included, but man pages?!

heh?? man pages are included.

Last edited by DonVla (2007-11-17 05:43:25)

tam1138 · 2007-11-17 07:10:21

Right. Like I said, I sort of understand why html docs are not included. (I would still really like the option of having them, just in case I'm going to be offline, or the internet versions aren't available for whatever reason.) And no, man pages are not always included. I had to file a bug to get them into openssl, and they aren't in db. These spring immediately to mind; I'm sure there are others.

Allan · 2007-11-17 07:19:52

Well file a bug for db too... AFAIK, man pages should be included and if not then that is an over-site of the packager.

dolby · 2007-11-17 09:15:12

man pages are definately bugs. about the reasons for stripping docs, search the forum. there are numerous discussions over the years about that

Last edited by dolby (2007-11-17 09:15:33)

tam1138 · 2007-11-17 17:44:16

Actually, it appears that db doesn't come with manpages; the only thing they provide are the HTML docs. Lame.

Thanks for the pointer, dolby, I'll poke around.

tam1138 · 2007-11-17 18:40:27

Okay, I went groveling through the forums and the mailings lists and here is what I found:

I have yet to see a compelling reason to yank the html docs. In fact, some of the arguments are ridiculous. (Disk space? Please; not with today's disk sizes. Somebody even wanted to get rid of headers and static libraries, too! Are you high?) Furthermore, the only reasonable argument I could see (bandwidth) was refuted somewhere in one of those threads.

Is the added "burden" of including detailed documentation in packages enough to offset the inconvenience of (judging from the mailing lists) a non-trivial number of users who are otherwise forced to manually download and extract documentation whenever there is a new release? What "burden" is this, exactly? Dev effort? Server bandwidth? Server disk? User bandwidth? User disk?

cactus · 2007-11-17 23:28:45

tam1138 wrote:

Seriously, I'd like to know why this is an unspoken part of The Arch Way and then I'd like it fixed, because it's Wrong.

Unspoken?
http://wiki.archlinux.org/index.php/FAQ … ackages.3F

You might want to read the actual "The Arch Way" as well.
http://wiki.archlinux.org/index.php/The_Arch_Way

Arch includes man pages.
Nobody is stopping you from making your own info/html-doc packages.
Nobody is stopping you from putting them up somewhere for anyone/everyone to use.

Demanding that info/html-docs be included might be the wrong tactic to take. It sure didn't make me feel warm and fuzzy.

peets · 2007-11-18 02:05:47

cactus wrote:

Demanding that info/html-docs be included might be the wrong tactic to take. It sure didn't make me feel warm and fuzzy.

...but ...but tam1138 is speaking about missing man pages, and not complaining about other fancy forms of doc!

cactus · 2007-11-18 04:03:20

o.O

Reading the later posts does seem to imply that.
The first post seemed to lack a bit of clarity I guess.

Arch Linux

#1 2007-11-17 05:32:22

docs?

#2 2007-11-17 05:39:17

Re: docs?

#3 2007-11-17 07:10:21

Re: docs?

#4 2007-11-17 07:19:52

Re: docs?

#5 2007-11-17 09:15:12

Re: docs?

#6 2007-11-17 17:44:16

Re: docs?

#7 2007-11-17 18:40:27

Re: docs?

#8 2007-11-17 23:28:45

Re: docs?

#9 2007-11-18 02:05:47

Re: docs?

#10 2007-11-18 04:03:20

Re: docs?

Board footer