No doc?

sullivanva · 2005-08-13 21:08:48

I thought I was losing my mind.

The dang makepkg wasn't packaging the doc directory for a package I was making.

Then I found this in makepkg:

# remove info/doc files
cd $startdir
rm -rf pkg/usr/info pkg/usr/share/info
rm -rf pkg/usr/doc pkg/usr/share/doc

I understand the reasons, but are there alternate strategies for keeping the stuff?

Is this format acceptable?

/usr/share/vim/doc
/usr/share/scrollkeeper/doc
/usr/share/t1lib/doc

arooaroo · 2005-08-14 10:41:24

As far as I'm aware docs and info files are scrapped in favour of man files and the internet. There was a discussion recently about how certain packages really benefit from having their doc files, and I think there was talk of a strategy for packaging up docs as separate packages.

I like the idea of having a "whitelist" - a user defined list of packages for which you want docs to remain. But I think that would be a pain to implement.

The alternative is to makepkg those which you want the docs for and comment out the offending lines from the PKGBUILD.

archdaemon · 2005-08-14 22:17:00

I changed makepkg to read

# remove info/doc files
cd $startdir
rm -rf pkg/usr/info pkg/usr/share/info
if [ -z $PRIVATE_BUILD ]; then
    rm -rf pkg/usr/doc pkg/usr/share/doc
fi

and then just 'export PRIVATE_BUILD=Y'.

I think the policy is frankly daft. Seems like there was a proper way to do it, like a flag to pass or something to set in makepkg.conf but I couldn't find it again, so just did that. `Course, I guess I'll have to keep that in sync with each pacman upgrade.

sullivanva · 2005-08-14 22:36:12

For a second there I thought you were the owner of the makepkg script saying you were going to change it ...

I got around the problem by moving the stuff to a different directory.

I understand the basic reason behind it, but sometimes a package provides a lot of doco, because you need it.

So in my case i just put this in the PKGBUILD:

/bin/mkdir -p $startdir/pkg/usr/share/mhonarc/doc/
cd $startdir/src/MHonArc-$pkgver/doc/
/bin/cp -pr * $startdir/pkg/usr/share/mhonarc/doc/

No harm, no muss.

archdaemon · 2005-08-14 22:59:34

sullivanva wrote:

For a second there I thought you were the owner of the makepkg script saying you were going to change it ...

Nope, sorry.

sullivanva wrote:

I got around the problem by moving the stuff to a different directory.
I understand the basic reason behind it, but sometimes a package provides a lot of doco, because you need it.
So in my case i just put this in the PKGBUILD:
/bin/mkdir -p $startdir/pkg/usr/share/mhonarc/doc/
cd $startdir/src/MHonArc-$pkgver/doc/
/bin/cp -pr * $startdir/pkg/usr/share/mhonarc/doc/
No harm, no muss.

Yep, that'll do, but sometimes packages (for builtin help functions and the like) expect files to be in /usr/doc/foo. --with-data-dir=/something/that/wont/be/deleted might do for some of those but not all. Just treating the docdir normally should work for everything - except Arch's packaging guidelines.

phrakture · 2005-08-15 16:58:01

archdaemon wrote:

I think the policy is frankly daft. Seems like there was a proper way to do it, like a flag to pass or something to set in makepkg.conf but I couldn't find it again, so just did that. `Course, I guess I'll have to keep that in sync with each pacman upgrade.

The policy is there for many reasons:
a) Arch is a networked distro.... you're expected to keep your system up to date and are expected to have an internet connection
b) Internet documentation is either the same or newer than installed documentation, and therefore "better" in terms of updated-ness.
c) Alot of projects now are using wikis for documentation
d) Installed documentation is a waste of space that never gets used. I think Windows 98 installs something like 150 MB of help files and another big chunk of video help - would you like Arch to do that? Oh, now package X has changed from 2MB to 8MB because they decided to include doxygen docs for their entire API in html, postscript, and pdf... enjoy!
e) When was the last time anyone here had a problem and *didn't* think "google" right away? I seriously doubt anyone has ever thought "Hmmm grub error 23132? Better fire up Gnome Help Center (or whatever it's called)"

archdaemon · 2005-08-15 17:32:54

phrakture wrote:

The policy is there for many reasons:
a) Arch is a networked distro.... you're expected to keep your system up to date and are expected to have an internet connection

And if your problem *is* your network connection?

b) Internet documentation is either the same or newer than installed documentation, and therefore "better" in terms of updated-ness.

This is simply incorrect. Unless you wish to find and access cvs or repetitively download entire source tarballs there are very often docs and most especially samples and helper scripts and demos that are not on websites.

c) Alot of projects now are using wikis for documentation

As a former wiki sysop I can say that wikis are wonderful and invaluable and unofficial and unreliable. You have to be very careful with wikis. Basically, it excuses developers from producing quality docs. They can just say 'Look! Wiki!' Understandable and certainly better than nothing and often even better than official docs but still flaky.

d) Installed documentation is a waste of space that never gets used. I think Windows 98 installs something like 150 MB of help files and another big chunk of video help - would you like Arch to do that? Oh, now package X has changed from 2MB to 8MB because they decided to include doxygen docs for their entire API in html, postscript, and pdf... enjoy!

An entire install of Window98 is about 180MB (less the optional videos) and what's that got to do with anything? All the damned internationalization crap is a waste of space to me but pretty valuable to others. Can I export 'Monolingual=Y' and get all *that* junk removed? All the knome deps and *.desktop files and whatnot are a waste to me. One man's fat is another man's lean.

And it's all so damned arbitrary. /usr/share/ImageMagick-6.2.3/LICENSE is on my system - and probably yours to. Dunno what I'd do without *that*. But /usr/doc/muttng/manual.txt *wouldn't* be if I hadn't built my own. All because of where programs happen to put things and that a wild blind deletion of */doc/* is policy.

e) When was the last time anyone here had a problem and *didn't* think "google" right away? I seriously doubt anyone has ever thought "Hmmm grub error 23132? Better fire up Gnome Help Center (or whatever it's called)"

Google is not the only solution and people's reliance on it is questionable. I use it frequently but, even when restricted to google/linux I'd *much* rather search my own filesystem with my own tools with a much smaller database and *far far* fewer false returns, plain junk, and advertising.

sweiss · 2005-08-15 17:59:17

I'm with archdaemon here. A lot of webpages forward you to the package's documentation rather than having it online, and also some applications make internal use of their documentation as well as some manpages which forward you to such documentation. Sometimes webservers are taken down and so on.

I'm not much of a bash expert, but can't makepkg use 'mv' instead of 'rm' and automatically generate optional -doc packages or something similar?

phrakture · 2005-08-15 18:11:33

I just really can't understand why this is a big deal... in the past 3 months I haven't touched any docs beyond <tab><tab> and -h/--help... I mean what are you people doing that requires offline documentation that you can't gleen from a man page?

How about this - you guys throw together some "doc" packages, that only contain the /usr/doc stuff, I will modify my makepkg and maintain them in the community repo - does that make everyone happy?

Just PM me when you upload them.

sullivanva · 2005-08-15 21:43:32

I'm not opposed to putting the docs out on the wiki. Not everyone needs a copy of the 100s of pages of docs that that come with mhonarc, for example.

I guess my question is where would we put it (some kind of special section?) and what would be the rules for posting their documentation on the Arch wiki?

phrakture · 2005-08-15 21:54:43

sullivanva wrote:

I guess my question is where would we put it (some kind of special section?) and what would be the rules for posting their documentation on the Arch wiki?

Not the wiki, I mean the AUR... make a PKGBUILD and I will provide the binaries in the community repo... I just have no idea what docs you guys are complaining about, so you'll have to make the PKGBUILDs yourselves and just PM me

sweiss · 2005-08-16 14:38:05

I'm not sure about archdaemon but I was referring mostly to various development tools and libraries, in which manpages are mostly non-existent.

phrakture · 2005-08-16 16:25:34

sweiss wrote:

I'm not sure about archdaemon but I was referring mostly to various development tools and libraries, in which manpages are mostly non-existent.

Heh, use different libraries!
Seriously I've stopped using certain libs because their documentation sucked and alot was undocumented... for instance I had one API call once, which the docs said returned "0 for failure, 1 for success, 2 for an unexpected error" and it was returning like 3932 or something...

cactus · 2005-08-16 16:45:28

Didn't you know you were supposed to drop all digits but the last two, divide by 8, bitshift to the right, and then you have 2! An unexpected error.
Gods man. Didn't you read the source?!

>_<

Arch Linux

#1 2005-08-13 21:08:48

No doc?

#2 2005-08-14 10:41:24

Re: No doc?

#3 2005-08-14 22:17:00

Re: No doc?

#4 2005-08-14 22:36:12

Re: No doc?

#5 2005-08-14 22:59:34

Re: No doc?

#6 2005-08-15 16:58:01

Re: No doc?

#7 2005-08-15 17:32:54

Re: No doc?

#8 2005-08-15 17:59:17

Re: No doc?

#9 2005-08-15 18:11:33

Re: No doc?

#10 2005-08-15 21:43:32

Re: No doc?

#11 2005-08-15 21:54:43

Re: No doc?

#12 2005-08-16 14:38:05

Re: No doc?

#13 2005-08-16 16:25:34

Re: No doc?

#14 2005-08-16 16:45:28

Re: No doc?

Board footer