While preparing for my first vacation ever next week, I’ve been trying to write up more content on my guide so that at least my fellow developers in LScube have a references of what I’ve been doing, and Gentoo developers as well, as lately I’ve been asked quite a few interesting questions (and not just them).
So, first of all, thanks to David (user99) who cleaned up the introduction chapter, and to Gilles (eva) who gave me the new stylesheet (so that it doesn’t look as rough as it did before, it also narrows the lines so that it reads better. It might not be the final style, but it really is an improvement now.
As for my changes, I’ve been trying to change slightly the whole take of the guide, trying to write up complete working examples for the readers to use, that are listed in the main page. At the same time, I’m trying to cover the most important, or less known, topics, with particular attention to what people asked me, or what I’ve been using on projects which is not very well known. The list of topics added include:
AC_CHECK_HEADERSto get one out of a prioritised list of headers;
AC_ARG_*macros (enable, with and environment variables);
AS_HELP_STRINGto document the arguments;
AC_ARG_WITHto set up automatic but not automagic dependencies;
- using automake with non-recursive makefiles (including some of the catches);
- improved automake silent-rules documentation;
- using external macro files with autoconf (work in progress, for now only autoconf with no extras is documented).
I’m considering the idea of merging in some of the For A Paralllel World articles, at least those dealing with automake, to complete the documentation. The alternative would be to document all these kind of problems and writing something along the lines of “A Distributor’s Bible”… the problem with that idea is that almost surely somebody will complain if I use the name “Bible” (warning: I’m not a Catholic, I’m an atheist!)… and if I am to call it “The Sacred Book of Distributors” I’ll just be having to dig up all the possible mocks and puns over various religions, ‘cause I’ll be almost surely writing the ten commandments for upstream projects (“Thou shall not ignore flags”, “Thou shall version your packages”), and that also will enter a politically correctness problem.
Oh well, remember that I do accept gifts (and I tried not putting there the stuff that I’ll be buying next week… I already told my friends not to let me enter too many shops, but I’ll be following them and that’s not going to be a totally safe tour anyway…).
I’m a very conservative Christian, but I don’t see anything wrong with using the word “Bible”. In fact, it sort of honors the Bible to use it in that way, since it suggests that it is the standard to which other documents must measure up.Furthermore, the word bible is from the Greek biblios which just means “book”. There’s really nothing that sacred about the word itself — just what’s IN the book.By the way, I’ve really enjoyed your “Parallel world” series. I do think that you are a little quick to dismiss some of the serious difficulties that developers have with the autotools. I’ve used both auto* and cmake extensively and I have to say that I find auto* endlessly frustrating. The documentation is poor (the info files are often out of date, there are very few good tutorials, and new versions often invalidate the information in what little documentation I can find) and many of the important feature are very difficult to understand. It breaks a lot between versions, too.
style looks much nicer and displays the new layout throughout. Looks as though the new page/doc should help the previous poster…as intended. 😉
@atomopawn I’m not afraid of Christians for what concerns using the word “Bible”, I’m more concerned about other religions… and the fact that I’d find it tremendously difficult to avoid at least mocking the structure of that.As for autotools vs cmake, again… as user99 pointed out, the fact that there isn’t really any good documentation about autotools is the reason why I’m writing the Autotools Mythbuster guide. Once you do know how to do the common tasks, using autotools _is_ piece of cake.The problem that are there are due to a layering of multiple failures over time: * official documentation wasn’t updated for long periods of time, starting with the autobook (that, as far as I know, is still _not_ updated); * lots of projects made up syntax and macros that don’t comply at all with the autoconf standards, and these are the examples that most people look into when creating new projects; * projects like KDE created FUD around autotools after judging them for bastardisations that are _not_ mainline (the KDE3 build system).CMake didn’t really have a totally up-to-date guide when I first looked into it, it actually was quite out of sync with the actual implementation. And it has the same problem with macro files (pardon, cmake modules) as autoconf from one point of view. But at least Kitware went around giving the good example, fixing the broken stuff before it was used as examples, nobody up to now did that with autotools.And in particular, all the documentation I found before about autotools focuses on explaining the interface, but not giving examples of use, because they point on the (pretty high) flexibility rather than usability; I have a different idea, and that’s why my guide differs, and tries to give ready examples as well.
g’morning,Needs a script to walk the tree for a correction. this would take to long to do this page by page.in English the articles ‘a’ or ‘an’ is solely determined by what follws as the first letter of the noun…if noun starts with consonant use ‘a’ if noun starts with vowel use ‘an’It’s aminor thing in the overall context but something editors do. 😉
I guess my problem there is with stuff like “sh”, since I often pronounce it mentally like in Italian, with a “s” that’s very much a consonant 🙂
This is one of the things makes english tough for non-native speakers…so many little rules. *rolls eyes*Also not real fond of italicized ‘table of contents’ harder for my poor eyes to read.You are very close here to a document that could be published…with some extensive editing . I will continue to try to help…but like you I cannot do this full time. I have to feed my family so I can only give a couple hours a day …least they are getting to be more productive hours.
Well, I do know the rules, it’s just that I forget of them while I’m trying to convey a topic 🙂 I didn’t spend too much time re-reading through what I wrote up to now, because I’m aiming more to provide the information than cleaning it up (thus why your help is certainly appreciated :)).Right now I’m not really aiming for publishing this, there are enough books being written about autotools it seems, so it’s going to remain what it is: an online documentation.Considering it’s an all-voluntary work it’s shaping up quite well, isn’t it? 🙂
Indeed…very well. ToC looks much better thanksI am enjoying the learning experience and am quite happy to finally be able to contribute to something meaningful…and frankly though it is only a small help I am pleased to find I seem to have a talent for technical writing/editing. I was very pleased that you found my commits good enough to include
and it is also entirely ok to not worry about dotting the i’s and crossing the t’s when doing a rough draft…it is more productive to get it on paper/doc first then restructure later…so no problem…I only explained the rule because it was not evident from the doc that you knew it …(please smile I am as I write that last line)
On the tangent of a/an: I always put ‘an’ in front of vowel sounds, and ‘a’ in front of consonant sounds. ‘an honest’, ‘a house’, ‘an SQL’, ‘a CVS’, ‘an under-used’, ‘a used’. Personally, I find anything else insane.
It frankly sounds better that way. so be it 😉