Re: make documentation
On Sun, Jun 27, 2021 at 12:40:21PM +1000, Reuben ua Bríġ wrote: > i would like to prefix this by saying i am writing this as a user > giving feedback and not a developing giving patches and anyone who has > a problem with that can go shove it rather than telling me to shut up. > > i noticed for a lot of the ports to openbsd, even in base, a lot of > documentation is either missing or, how shall i put it, over-compiled. > > some examples in my memory are: > > texlive* installs e.g. PDF documenation and removes TeX sources, even > though in many cases the TeX sources are an integral part of the > documentation. > > man-pages-posix installs cat files rather than man files. (b.t.w. the > man tools do work with section 0, you just need change the file > extension: i would suggest .3p for compatibility with current section.) > > anyway i think users would benefit from including more documentation > when it is in the sources, but, you know, its your time, so dont do it > if you dont want, just dont be prissy about it. > > TeXlive is already problematic enough to package properly, it is huge and each new release takes some hand-holding. Plus, it's the largest packages we ship. If you really need the source, I suggest you just grab the distfiles and per-use them... or open some kind of bug-report with the guys who actually ship TeXlive. Specifically: out of the (literally) thousands of pdf files we ship, there are probably some TeX source that should go along with it, but there's no way we're shipping them all, and there's no way we're sorting through them by hand !
Re: make documentation
> Date: Mon, 28 Jun 2021 09:46:01 +0100 > From: Stuart Henderson > I think you need to adjust your attitude if you're going to continue > posting here. yall are happy to insult everyone else personally, or sit by and watch theo do so, but if anyone suggests your changes maybe arent the absolute greatest thing in the world making ground-breaking improvement in security and simplicity---well, then i guess their attitude need adjusting. seeing as i mentioned theo, i ought to emphasize that i *really* didnt object to the man.conf change at the time. i had the 4.3 bsd manual and couldnt see any problem with the change. it was the 4.4 bsd man that changed my mind.
Re: make documentation
On 2021/06/28 18:20, Reuben ua Bríġ wrote: > > Date: Sun, 27 Jun 2021 21:47:01 +1000 > > From: Reuben ua Bríġ > > > im hopeful i can get the sources good enough for /usr/local/man/posix > > = i hope i can get them to run through man properly > > > but if not, in lieu of an option to make man prefer formatted files: > > = the new man is arrogant in ignoring properly formatted pages: it > tries to format pages itself, even when it cant. there is no flag to > disable the arrogance of man. > > > CAT=/usr/local/man/posix > > MAN=/usr/local/share/doc/posix/man > > mv cat* $CAT > > mv man* $MAN > > cat >$CAT/man.conf <<. > > manpath $CAT > > manpath $MAN > > . > > = the new man can be tricked into preferring formatted pages by > putting them in a different manpath and putting it first in a > special configuration file /usr/local/man/posix/man.conf > > > chmod +x /usr/local/bin/man_posix # if eqn desired for PDF, etc. > > = the new man arrogantly assumes it is the sole keeper of manuals. > this assumption was outdated when uunet on 4.3 bsd gave way to the > internet. this was fixed in 4.4 bsd but obsd 5.7 regressed. so a > script should be provided that knows about something that can properly > typeset the manuals when desired, and, when terminal output is wanted, > conveniently call man -C /usr/local/man/posix.conf > I think you need to adjust your attitude if you're going to continue posting here.
Re: make documentation
> Date: Sun, 27 Jun 2021 21:47:01 +1000 > From: Reuben ua Bríġ > im hopeful i can get the sources good enough for /usr/local/man/posix = i hope i can get them to run through man properly > but if not, in lieu of an option to make man prefer formatted files: = the new man is arrogant in ignoring properly formatted pages: it tries to format pages itself, even when it cant. there is no flag to disable the arrogance of man. > CAT=/usr/local/man/posix > MAN=/usr/local/share/doc/posix/man > mv cat* $CAT > mv man* $MAN > cat >$CAT/man.conf <<. > manpath $CAT > manpath $MAN > . = the new man can be tricked into preferring formatted pages by putting them in a different manpath and putting it first in a special configuration file /usr/local/man/posix/man.conf > chmod +x /usr/local/bin/man_posix # if eqn desired for PDF, etc. = the new man arrogantly assumes it is the sole keeper of manuals. this assumption was outdated when uunet on 4.3 bsd gave way to the internet. this was fixed in 4.4 bsd but obsd 5.7 regressed. so a script should be provided that knows about something that can properly typeset the manuals when desired, and, when terminal output is wanted, conveniently call man -C /usr/local/man/posix.conf
Re: make documentation
> Date: Mon, 28 Jun 2021 14:16:24 +1000 > From: Reuben ua Bríġ > my experience with the awk manual is the the mandoc ouput and cat > file are pretty much the same. in both, the table is too wide for > 80 columns and wraps, making it impossible to read, but again, in > both, its fine if you use a wider terminal. > Date: Mon, 28 Jun 2021 14:31:57 +0959 > From: Reuben ua Bríġ > also there is the leading problem in for -T html > but i see you are worried about whether mandoc really understands the output of man -T lint -l man1p/awk.1p seems pretty harmless.
Re: make documentation
> Date: Mon, 28 Jun 2021 14:16:24 +1000 > From: Reuben ua Bríġ > my experience with the awk manual is the the mandoc ouput and cat > file are pretty much the same. in both, the table is too wide for 80 > columns and wraps, making it impossible to read, but again, in both, > its fine if you use a wider terminal. also there is the leading problem in for -T html and no, you wont rope me into improving mandoc when i can use sed. > not ideal, but i dont see groff formatting it any better. > but i see you are worried about whether mandoc really understands it. whose to say its `correct' for groff anyway? in fact, it isnt.
Re: make documentation
> Date: Sun, 27 Jun 2021 16:52:22 +0200 > From: Ingo Schwarze > man1p/awk.1p just commenting on the output, net whether the source is `correct', but my experience with the awk manual is the the mandoc ouput and cat file are pretty much the same. in both, the table is too wide for 80 columns and wraps, making it impossible to read, but again, in both, its fine if you use a wider terminal. not ideal, but i dont see groff formatting it any better. but i see you are worried about whether mandoc really understands it.
Thanks for all the docs; WAS: make documentation
Reuben ua Bríġ writes: > > Date: Sun, 27 Jun 2021 15:28:49 +0200 > > From: Ingo Schwarze > > > I literally spent years of my life improving that. > > and im sure it is much better for it. > > ... > > good on em. why is it easier to get third party binaries than the > openbsd source? the whole reason i use openbsd is for the source, yet > folks just seem to keep trying to make source harder to get at. I have been a bit of a loudmouth on this and other OpenBSD lists before so I've stepped back to cool down but I can't leave this one be, this is just ridiculous. OpenBSD doesn't make sources available? The documentation is poor? What the hell are you smoking? Keep it. I would also like to call out Ingo Schwarze as being a fantastic example of how to deal with commentators from the peanut gallery (including myself iirc). Despite his significant and largely unthanked work being directly impugned he has nevertheless taken the time to repeatedly and patienty deal with a complainer who is frankly not listening and in general being an obnoxious little tit, and still finds a way to turn it all into a positive contribution. OpenBSD makes the source for everything it builds available. It is built for developers who want to hack on it and with it, and (surprise!) they need its sources. The means of getting them are, for the benefit of those (potential) developers, documented in many places including the best set of manpages in any open source community (see also postgres) as well as OpenBSD's FAQs and its other texts. I have nothing to actually add to this discussion so but thank you OpenBSD for making for me for free a fantastic playground for programming in (with extraordinary documentation) and Reuben, take a leaf out of my book: Shut up and hack. Matthew
Re: make documentation
> personally i would like to patch man so that it calls make (with a > special makefile), so it could be extended ooh, i just used the freebsd manual server to look at the 4.4 BSD lite page for man.conf. i think i had better upgrade! to 4.4 BSD. honestly i dont mean to be snide. i wish it was this way. but ooh how i wish i had 4.4 on my amd64!
Re: make documentation
> personally i would like to patch man so that it calls make (with a > special makefile), so it could be extended ugh. look at the problem of man-pages-posix. your mandoc program cant format them, so you use another program to output the old output format of man, and then man reads those. now, in those slides you linked to, you one of the virtues you of mandoc you were extolling was its ability to output in html, pdf, the works. so, do you update man to handle these new formatted pages? no. oh, so will you remove its ability to handle the old formatted pages? no. oh, so will you at least strongly discourage their use? no, you say they *must* be used instead of man sources, and you will defend to your death any patch to man to make it able to show its own output. W. T. F. > easier to handle for porters argh!!! this is my point! if you arent going to bother to write documentation for man, then write man for your documentation! !@#$%^&* > Try to write complete sentences that are as clear as possible, the first time i tried to write sentences i was told to either provide code or shutup. > Regarding v7man... Anything wrong with that? that is volume 1. i.m.o. the second installment was better.
Re: make documentation
Hi, Reuben ua Brig wrote on Sun, Jun 27, 2021 at 09:47:01PM +1000: >> Date: Sun, 27 Jun 2021 10:29:12 +0100 >> From: Stuart Henderson Judiging from marc.info and from my own mailbox, i fail to find the original copy of this posting by Stuart. Reuben, did you publicly quote a private mail, or am i missing something? >> Seems I was (and the port Makefile) was wrong about it being tbl No, Stuart, you were spot-on. For example, consider gmdiff man0p/complex.h.0p gmdiff man1p/awk.1p >> vut there aee some big problems with equations e.g. in float.h, math.h. As far as i am aware, and according to the extract from my ports notes file that i posted recently, the problems with eqn(7) are mostly excessive spacing caused by weird syntax involving useless quoted space characters in the eqn source code. That's likely much easier to fix than the very serious tbl parsing issues, but hardly high priopity given that i don't recall ever having seen similar input syntac anywhere else. >> btw the source manpages *are* installed but (probably due to how >> pkg_create handles manpages in USE_GROFF ports) they're tarred up. Yes, they are installed, but only for licensing reasons in the past (that may no longer exist). The reason they are tarred up is that we don't consider it useful to install two copies of the same text. When cat pages are needed, we don't want the sources alongside. So zhuk@ decided to waste as little space as the license allowed when he set up the port in 2014. > having only seen float.h, mandoc did slightly better in one place where > it included a sum where the cat file only had . Yes. I improved handling of mathematical symbols and Greek letters in both mandoc and groff terminal output not long ago, but eqn(7) handling for the terminal is likely better with mandoc than with groff: i spent significant work on that based on the excellent foundations that Kristaps laid. > personally i would like to patch man so that it calls make Over my dead body. > (with a > special makefile), so it could be extended to e.g. cat pkg-readmes; I dimly remember that moving pkg-readmes into a dedicated section of the manual pages was proposed in the past and rejected; i don't remember why exactly, it may have been because the existing format is easier to handle for porters, and the texts are so short that it usually matters relative little for users; not sure. > but first i will see how posix-man-pages and v7man go. I don't think i understaood all you said, some of your code snippets seemed cryptic and of unclear purpose. Try to write complete sentences that are as clear as possible, please. Regarding v7man, are you referring to https://man.bsd.lv/?query=.=1=UNIX-7 Anything wrong with that? Yours, Ingo
Re: make documentation
> Date: Sun, 27 Jun 2021 15:28:49 +0200 > From: Ingo Schwarze > I literally spent years of my life improving that. and im sure it is much better for it. > texlive documentation is definitely a maze... tex... well, half the point of it is that once you get it working, you can run it on old files. sure, i would never wish to get it working, but as a user, it only takes me a few seconds to see that some very fundamental bits, like the tex examples of don knuth and pdftex are missing. it hard to get texlive up and running. i have difficulty in believing it is so hard to either not rm some tex code, or, as i have had to do, run tar xfz on some files from ctan. > As a matter of fact, it installs *both*. ugh, no it doesnt. leaving something in a zipped archive is *not* installing it... just ask any makefile. > *and the nroff source is included* good on em. why is it easier to get third party binaries than the openbsd source? the whole reason i use openbsd is for the source, yet folks just seem to keep trying to make source harder to get at. > That's a non-issue as long as mandoc cannot handle the POSIX manuals > at all. give it more credit. it handles a lot of it just fine. > Besides, 3p is Perl in OpenBSD, so that would a bad choice. and what, 3 isnt in openbsd? but yes, i did think ?x might be better. > You don't say? :-) i do indeed, and i mean it. i honestly found the 4.3 BSD Reno supplementary docs (or UNIX V7 volume 2 with a BSD Daemon on the cover) in the library here more helpful than most of the OpenBSD documentation. some stuff on vi from a tar on some google group was also good (reminds me, vi gets confused and crashes if you repeatedly open the same file.) > manual page form certainly important for someone looking to maintain the documentation: but as someone who mostly just wants to read it, i really couldnt give a damn what format it is in, so long as i can page it with a single command. now, and index of terms, now that would impress me. > not too long ago, exactly as you are asking for. > Improving mandoc(1) such that it becomes able to handle > man-pages-posix ugh, seriously. first i say mount(8) and all the devs see is mount(2). then i say man(1) and you see mandoc(1). I DONT CARE ABOUT YOUR DOCUMENTATION FORMAT. i use tex and utf8 and thats good enough for me. the guy who does ports/* doesnt care about your format either, and he regards his creation compudocxmlinfo+ with the same love and care as you do mandoc. he is not going to learn mandoc, and i am not going to learn both mandoc and compudocxmlinfo+ just so i can translate it because every porter has maintained something oh so big and therefore cant be stuffed to translate it either. they are *computer* formats. let the damn machine do the translation. if its mandoc, let man call mandoc, if its html, let man call w3m---but dont call me, goddammit. > > so they still need to be formatted with groff. > > Exactly. Reuben, if you don't see that mandoc output is broken > for these pages, you need to look harder. oh yep, nobody can make suggestions, because you guys dont get paid, oh but your users apparently do get paid to fix your system. ugh, again, you didnt read. THE GROFF OUTPUT IS BROKEN. in some ways *worse* than mandoc.
Re: make documentation
Hi Reuben, Reuben ua Brig wrote on Sun, Jun 27, 2021 at 05:26:29PM +1000: > From: Stuart Henderson >> Maybe not for man-pages-posix, it looks like embedded tbl(7) support >> is needed. mandoc doesn't do this, so they still need to be formatted >> with groff. > cheers. will see what i can do. i have not noticed any problems with > the output of man so far (havent tried html etc.), All output modes are wqually broken because these are parsing issues rather than formatting issues. > and am not familiar with roff, so are have you noticed any problem > pages in particular? See my last mail to you, it contains some examples - not a full list though since even drafting a full list would cause significant work, of limited usefulness given how difficult it is to fix all that. If something is so difficult that there is no chance fixing it any time soon, spending lots of effort on describing all the problems in detail is a waste of time. > p.s. just tried MANPAGER=w3m man -T html 3p sigaction; and the table > for struct sigaction looks alright, though there are too many empty > lines in the C text under `Establishing a Signal Handler'. That's a relatively minor, purely HTML formatting issue that would definitely not stand in the way of using mandoc. In general, -Tascii and -Tutf8 output have a much higher quality and are much more important than HTML output (even though mandoc HTML output is vastly superior to groff HTML output, and lots of work was spent, and is being spent, on improving HTML output). What you are reporting here are valid concerns in the mandoc roff(7) to HTML formatter, which is among the youngest formatting modules. Using inside for .nf may be less than ideal, and representing .P inside .nf by closing and reopening the even less so. It's not completely trivial because it likely can't be solved in roff_html.c alone but the interactions with html.c and possibly man_html.c and maybe even mdoc_html.c need to be considered. So i added your report to the TODO file for now: - HTML formatting of .nf should avoid and not close and re-open on .P Reuben ua Brig 27 Jun 2021 17:26:29 +1000 loc ** exist ** algo * size * imp ** Thanks for the report, Ingo
Re: make documentation
Hi, Stuart Henderson wrote on Sun, Jun 27, 2021 at 08:17:40AM +0100: > On 2021/06/26 22:06, Mike Larkin wrote: >> On Sun, Jun 27, 2021 at 12:40:21PM +1000, Reuben ua Brig wrote: >>> i would like to prefix this by saying i am writing this as a user >>> giving feedback and not a developing giving patches and anyone who has >>> a problem with that can go shove it rather than telling me to shut up. >>> >>> i noticed for a lot of the ports to openbsd, even in base, a lot of >>> documentation is either missing or, how shall i put it, over-compiled. This remark is amazing. I literally spent years of my life improving that. Please read http://www.openbsd.org/papers/bsdcan18-mandoc.pdf slides 35 to 40. Page 36 documents that i improved what you are asking for by a factor of 180 (it is now one hundred and eighty times better than it used to be). What you are talking about is literally the last 3 permille, the last 30 ports out of 9000. >>> some examples in my memory are: >>> >>> texlive* installs e.g. PDF documenation and removes TeX sources, even >>> though in many cases the TeX sources are an integral part of the >>> documentation. Texlive is *the* ultimate monster port (as far as *individual* ports go; there are no doubt *groups* of ports maintained by individual people or small teams that are even worse, far worse, like GNOME and KDE and mozilla - and OK, admittedly, there are a few other individual monsters, like chrome). I admire Edd for maintaining texlive over all those many years. Nothing about that beast is simple, not even understanding the vast amount of stuff it contains. And yes, texlive documentation is definitely a maze, half a continent of swamps and deserts scattered among jungles of code, containing no end of wild beasts and beautiful gems. Improving that is... some kind of an undertaking, you know. >>> man-pages-posix installs cat files rather than man files. As a matter of fact, it installs *both*. For the 2013-a version, it was forced to do so by this annoying former requirement in the file POSIX-COPYRIGHT: [...] Redistribution of this material is permitted so long as this notice and the corresponding notices within each POSIX manual page are retained on any distribution, *and the nroff source is included*. [...] (my emphasis) In the 2017-a version, that requirement was removed, which jasper@ apparently missed when updating the port last November. I guess i should send a patch to no longer install the source tarball. >>> (b.t.w. the man tools do work with section 0, you just need change >>> the file extension: i would suggest .3p for compatibility with >>> current section.) That's a non-issue as long as mandoc cannot handle the POSIX manuals at all. Besides, 3p is Perl in OpenBSD, so that would a bad choice. >>> anyway i think users would benefit from including more documentation >>> when it is in the sources, You don't say? :-) By the way, it's not just mandoc. For example: https://undeadly.org/cgi?action=article=20190419101505 In particular, after reading the piece, look at the last use case at the very bottom. "The /usr/xenocara/ tree contains about 250 DocBook files. Some of them might contain information worth extracting. I plan to look into that together with matthieu@." After that, look at stuff like man fonts man XKB-Config man XKB-Enhancing man shapelib man synclib man xtest1 man Xmu man drmAvailable man drmHandleEvent man drmModeGetResources man 7 drm man drm-kms man drm-memory man xtrans That's all documentation that was made available in manual page form not too long ago, exactly as you are asking for. Admittedly, the effort stalled somewhat. The task here is extracting the gems from the swamp. Not all of these 250 documents are likely to really benefit users, and we don't want to promote crap. >>> but, you know, its your time, so dont do it >>> if you dont want, just dont be prissy about it. >> your diff to implement what you are asking for is welcome! > Maybe not for man-pages-posix, Right, Stuart, thank you for clarifying that. Improving mandoc(1) such that it becomes able to handle man-pages-posix is among the hardest remaining tasks to solve in mandoc. You are welcome to help improve mandoc if you want to, but you are definitly not welcome to try to make mandoc work with man-pages-posix. Even if you manage to, the diff will be so large, complicated, and intrusive that i won't have the time to review it properly. Here is the mandoc TODO lists: https://cvsweb.bsd.lv/~checkout~/mandoc/TODO?rev=HEAD As a beginner, look for entries that say "loc * exist * algo * size *". But be aware that even those aren't trivial and most of them pose traps for the unwary. If something is really easy, most of the time, it doesn't make it into the file at all but tends to gets fixed on the spot. My rating for making man-pages-posix work is "loc *** exist ** algo *** size **", i.e. it's a cross-module
Re: make documentation
> Date: Sun, 27 Jun 2021 10:29:12 +0100 > From: Stuart Henderson > Seems I was (and the port Makefile) was wrong about it being tbl vut > there aee some big problems with equations e.g. in float.h, math.h. > btw the source manpages *are* installed but (probably due to how > pkg_create handles manpages in USE_GROFF ports) they're tarred up. great to know about eqn: much thanks! having only seen float.h, mandoc did slightly better in one place where it included a sum where the cat file only had . im hopeful i can get the sources good enough for /usr/local/man/posix but if not, in lieu of an option to make man prefer formatted files: CAT=/usr/local/man/posix MAN=/usr/local/share/doc/posix/man mv cat* $CAT mv man* $MAN cat >$CAT/man.conf <<. manpath $CAT manpath $MAN . chmod +x /usr/local/bin/man_posix # if eqn desired for PDF, etc. --- SECTION 0. oh, i forgot, makewhatis skips man0*, so use makewhatis -a --- PATCH MAN. personally i would like to patch man so that it calls make (with a special makefile), so it could be extended to e.g. cat pkg-readmes; w3m index.html; use pkg_info; nroff section 2 of the V7 Unix manual. obviously this wouldnt be so much for base but rather for ports and users wishing to add their own notes to the system manual, to save searching /usr/local/ and writing special help scripts. but first i will see how posix-man-pages and v7man go. --- CC: LIST. p.s. last message i forgot to put the list in, so i resent it to the list. will continue to send to list unless someone says should do otherwise or seems obvious.
Re: make documentation
> Date: Sat, 26 Jun 2021 22:06:10 -0700 > From: Mike Larkin > your diff to implement what you are asking for is welcome! will do. > Date: Sun, 27 Jun 2021 08:17:40 +0100 > From: Stuart Henderson > Maybe not for man-pages-posix, it looks like embedded tbl(7) support > is needed. mandoc doesn't do this, so they still need to be formatted > with groff. cheers. will see what i can do. i have not noticed any problems with the output of man so far (havent tried html etc.), and am not familiar with roff, so are have you noticed any problem pages in particular? p.s. just tried MANPAGER=w3m man -T html 3p sigaction; and the table for struct sigaction looks alright, though there are too many empty lines in the C text under `Establishing a Signal Handler'.
Re: make documentation
On 2021/06/26 22:06, Mike Larkin wrote: > On Sun, Jun 27, 2021 at 12:40:21PM +1000, Reuben ua Bríġ wrote: > > i would like to prefix this by saying i am writing this as a user > > giving feedback and not a developing giving patches and anyone who has > > a problem with that can go shove it rather than telling me to shut up. > > > > i noticed for a lot of the ports to openbsd, even in base, a lot of > > documentation is either missing or, how shall i put it, over-compiled. > > > > some examples in my memory are: > > > > texlive* installs e.g. PDF documenation and removes TeX sources, even > > though in many cases the TeX sources are an integral part of the > > documentation. > > > > man-pages-posix installs cat files rather than man files. (b.t.w. the > > man tools do work with section 0, you just need change the file > > extension: i would suggest .3p for compatibility with current section.) > > > > anyway i think users would benefit from including more documentation > > when it is in the sources, but, you know, its your time, so dont do it > > if you dont want, just dont be prissy about it. > > > > your diff to implement what you are asking for is welcome! Maybe not for man-pages-posix, it looks like embedded tbl(7) support is needed. mandoc doesn't do this, so they still need to be formatted with groff.
Re: make documentation
On Sun, Jun 27, 2021 at 12:40:21PM +1000, Reuben ua Bríġ wrote: > i would like to prefix this by saying i am writing this as a user > giving feedback and not a developing giving patches and anyone who has > a problem with that can go shove it rather than telling me to shut up. > > i noticed for a lot of the ports to openbsd, even in base, a lot of > documentation is either missing or, how shall i put it, over-compiled. > > some examples in my memory are: > > texlive* installs e.g. PDF documenation and removes TeX sources, even > though in many cases the TeX sources are an integral part of the > documentation. > > man-pages-posix installs cat files rather than man files. (b.t.w. the > man tools do work with section 0, you just need change the file > extension: i would suggest .3p for compatibility with current section.) > > anyway i think users would benefit from including more documentation > when it is in the sources, but, you know, its your time, so dont do it > if you dont want, just dont be prissy about it. > your diff to implement what you are asking for is welcome!
make documentation
i would like to prefix this by saying i am writing this as a user giving feedback and not a developing giving patches and anyone who has a problem with that can go shove it rather than telling me to shut up. i noticed for a lot of the ports to openbsd, even in base, a lot of documentation is either missing or, how shall i put it, over-compiled. some examples in my memory are: texlive* installs e.g. PDF documenation and removes TeX sources, even though in many cases the TeX sources are an integral part of the documentation. man-pages-posix installs cat files rather than man files. (b.t.w. the man tools do work with section 0, you just need change the file extension: i would suggest .3p for compatibility with current section.) anyway i think users would benefit from including more documentation when it is in the sources, but, you know, its your time, so dont do it if you dont want, just dont be prissy about it.