I thought I would get around to writing up some documentation for setting up a personal web server using Apache. I'm aware that the gentoo-apache team will be making some rather significant changes and I will try to post updates to reflect the new changes as the Apache2 stable releases come out. Enjoy.
Created attachment 59161 [details] First Draft of Apache document Please comment.
you guys know i'm a fan of viewing new docs as a webpage... this is available at http://neverland.ncssm.edu/~smithj/gentoo/apache-conf.html /me begins to read
Created attachment 59172 [details, diff] apache-conf.xml.diff overview of what i changed in this patch: -minor grammer fixes many places -took out the justification for writing the doc. either swift/neysex will accept it or not; justification should be in the bug, not in the doc -added that the guide only talks about static content (not live stock quotes or some of apache's more difficult features/addons/mod_whatevers) -took out the emerge sync. users already know this, and its not mentioned in any other doc... -changed SSL to "Secure Socket Layer" in the table of USE flags -added a <pre> section on how to edit make.conf -wrapped text to 80 char/line in a few places -added a section about apache1/2 -cleaned up comments in code listings -changed Linux to Gentoo because you were not talking about only the kernel, but the entire OS -several coding style errors corrected -moved the second to the last paragraph about a todolist and faq to a comment at the top of the doc which is not rendered in a browser someone else needs to remove all the masive ammounts of trailing whitespace, but i forget how to do this... the newly patched doc is available at http://neverland.ncssm.edu/~smithj/gentoo/apache-config-new.html and the old one is still available at the above URL (comment #1)
s/comment #1/comment #2 ;-)
Created attachment 59173 [details, diff] apache-conf.xml.diff wow. sorry guys, i attached the wrong patch... this one's right
Thanks for polishing up and fine tuning the document! I'll be giving the document another good look sometime later today or tomorrow. I hope this document is worthy of being pushed out. I have a question to the developers as I'm unsure how this is normally handled. I plan on adding new content to this document over a lengthy period (lengthy as in after this document is published) of time so how are updates handled? Do I always submit a new bug report or keep going back to this one?
(In reply to comment #6) > I have a question to the developers as I'm unsure how this is normally handled. > I plan on adding new content to this document over a lengthy period (lengthy as > in after this document is published) of time so how are updates handled? Do I > always submit a new bug report or keep going back to this one? Generally, updates to a document are new bugs. If you have stuff to add (within a short period of time, say a week or so) I'd recommend that you take your time and add them to the doc....just a suggestion. Better way to do it IMHO if you have stuff "waiting in the wings" :)
Created attachment 59206 [details] Apache Doc Version 1.1 Here's the next version of the document. Removed the trailing whitespaces, cleaned up the tables, made some minor grammar changes to sentences, rephrased certain statements, applied and fixed up some of John's patch, bumped the version to 1.1, and a couple other misc. things. I'd host a webpage friendly version but I have no access to hosting and my own computer is on a non-routable IP.
(In reply to comment #8) > [snip] > I'd host a webpage friendly version but I have no access to hosting and my own > computer is on a non-routable IP. i only have the webspace because of my school. i'm happy to host. http://neverland.ncssm.edu/~smithj/gentoo/apache-conf.html has been updated to version 1.1 looks much better at first glance
you removed "All of the following modifications will be made to that file", and you never state that the file will be edited. i think it either needs to be stated that in a <pre> box, or you need to leave my line in. as for my <comment> restructuring, that was done so that comments could be organized more effeciently in the rendered html. if you have, for example... <comment># blar blah sdk;fgjdshkfgjhsdfkhs sdkfjash </comment> ... that will show up as two lines (and will need another "#"). if however, you have my method, it will be one line. there are a couple of grammer mistakes (i am a comma whore - you need more commas!), but we can catch those later, when content is more stable
(In reply to comment #10) > you removed "All of the following modifications will be made to that file", and > as for my <comment> restructuring, that was done so that comments could be > organized more effeciently in the rendered html. if you have, for example... > there are a couple of grammer mistakes (i am a comma whore - you need more > commas!), but we can catch those later, when content is more stable Oh, the "all of the following modifications" moved to an /impo tag, to greater emphasize the importance. I, slightly, changed the setenced to refer to "apache2.conf," instead of "that file," to erase any notion of ambiguity. After, I ran your patch and rendered the HTML, code listing 3.1, 3.2, and 3.6 seemed to show some extra lines in the very top of the box. It could be a render problem on my end, but my FireFox displayed one extra line in the beginning of each of those code listings with your patch. I skimmed a few of the existing Gentoo documentation, but none of the ones I looked at had an empty line at the top of the <pre> boxes that used <comment>. I'll look at the document again later to clean up some more grammar and re-examine the <comment>.
<guide link="/doc/en/apache.xml" lang="en"> lang="en" can be removed I think
Created attachment 59306 [details] Apache Doc Version 1.2 (In reply to comment #12) > <guide link="/doc/en/apache.xml" lang="en"> > lang="en" can be removed I think This is my first time doing one of these types of documents. I don't know what "should" be put in or "should not." So, I try and follow what the XML Guide and other Gentoo Docs do as well. I think I'll keep it there for now... unless there's some secret unspoken rules about tags like that not being needed? (First rule of Tag guide: Don't speak about Tag guide?) Here's another update to the document. Version has been bumped to 1.2, I've added some important information concerning the new changes the Gentoo Apache team have been doing, and I've added a warning on top of the document to indicate that it is still a draft.
Can you give us a hurl when you think the guide is finished? I'll then have one of the Apache herd peeps take a look at it.
Do you think the guide is ready? I'll mark this bug as NEEDINFO if I don't hear anything...
Hi, yeah I'm sorry about the long delay. I've haven't had a lot of free time lately. Last I checked, the way Gentoo handles the Apache documentation was undergoing some significant changes and the document does not fully reflect that. I won't be able to look over the Apache documentation until at least next week since July 4th break is on me.
FYI, Apache herd has some documentation as well and it is about to move tou our docs space. See bug 99539.
You can find the Apache documentation (developer, troubleshooting and upgrading) online already. It doesn't interfere with your document contentwise, meaning that it doesn't obsolete your guide. Yours does need updating to reflect the new locations.
Time out, marking NEEDINFO. Wham, please reopen when you have updated guide(s).
