From ff942e3f45fa1aec3647b0ccae0246beef0507a6 Mon Sep 17 00:00:00 2001 From: "Benj. Mako Hill" Date: Sat, 4 Jun 2005 00:08:05 +0000 Subject: [PATCH] I fixed a weird rending problem that was causing one character Author: mako Date: 2001/03/27 22:15:51 I fixed a weird rending problem that was causing one character indentation on all variable lists. I've also reread first section (intro) of the documention on the initial reread. --- FreeSoftwareDevelopmentHOWTO.sgml | 225 +++++++++++------------- FreeSoftwareProjectManagementHOWTO.sgml | 225 +++++++++++------------- 2 files changed, 206 insertions(+), 244 deletions(-) diff --git a/FreeSoftwareDevelopmentHOWTO.sgml b/FreeSoftwareDevelopmentHOWTO.sgml index 66fd9c6..713938b 100644 --- a/FreeSoftwareDevelopmentHOWTO.sgml +++ b/FreeSoftwareDevelopmentHOWTO.sgml @@ -332,6 +332,7 @@ I'd love for this HOWTO to gain the kind of international reach afforded by a translated version. + However, this HOWTO is still young and I have to yet to be contacted about a translation so English is all that is currently @@ -1016,14 +1017,12 @@ pages for more information and options. README or Readme - - A document containing all the basic installation, - compilation, and even basic use instructions that make up - the bare minimum information needed to get the program up and - running. A README is not your chance to be verbose but needs - to be concise and effective. An ideal README is at least 30 - lines long and more no more than 250. - + A document containing all the basic installation, + compilation, and even basic use instructions that make up the + bare minimum information needed to get the program up and + running. A README is not your chance to be verbose but needs + to be concise and effective. An ideal README is at least 30 + lines long and more no more than 250. @@ -1031,18 +1030,16 @@ pages for more information and options. INSTALL or Install - - The INSTALL file should be much shorter than the INSTALL file - and should quickly and concisely describe how to build and - install the program. Usually an install simply instructs the - user to run ./configure; make; make install and touches on - any unusual options that may be necessary. More advanced - users can usually avoid them but it's good practice to at - least glance at the file to understand what can be - expected. For most relatively standard install procedures and - for most programs, INSTALL files are as short as possible are - rarely over 100 lines. - + The INSTALL file should be much shorter than the INSTALL + file and should quickly and concisely describe how to build + and install the program. Usually an install simply instructs + the user to run ./configure; make; make install and touches on + any unusual options that may be necessary. More advanced users + can usually avoid them but it's good practice to at least + glance at the file to understand what can be expected. For + most relatively standard install procedures and for most + programs, INSTALL files are as short as possible are rarely + over 100 lines. @@ -1050,19 +1047,17 @@ pages for more information and options. Changelog, ChangeLog, CHANGELOG, or changelog - - A changelog is a simple file that every well-managed free - software project should include. A changelog is simple the - file that, as its name would imply, logs or documents the - changes to a program. The most simple way to do a changelog - is to simply keep a file with the source code for your - program and add a section to the top of the changelog with - each release describing what has been, changed, fixed, or - added to the program. It's a good idea to post the changelog - onto the website as well because it can help people decide - whether they want or need to upgrade to a newer version or - wait for a more significant upgrade. - + A changelog is a simple file that every well-managed + free software project should include. A changelog is simple + the file that, as its name would imply, logs or documents the + changes to a program. The most simple way to do a changelog is + to simply keep a file with the source code for your program + and add a section to the top of the changelog with each + release describing what has been, changed, fixed, or added to + the program. It's a good idea to post the changelog onto the + website as well because it can help people decide whether they + want or need to upgrade to a newer version or wait for a more + significant upgrade. @@ -1070,17 +1065,15 @@ pages for more information and options. FAQ - - For those of you that don't already - know. FAQ stands for Frequently Asked - Questions and the file is a collection of exactly that. FAQs - are not difficult to make. Simply make a policy that if you - are asked a question or see a question on a mailing list two - or more times, add it the question (and its answer) to your - FAQs. FAQs are more optional than the files listed above but - they can save your time, increase usability, and decrease - headaches on all sides. - + For those of you that don't already + know. FAQ stands for Frequently Asked + Questions and the file is a collection of exactly that. FAQs + are not difficult to make. Simply make a policy that if you + are asked a question or see a question on a mailing list two + or more times, add it the question (and its answer) to your + FAQs. FAQs are more optional than the files listed above but + they can save your time, increase usability, and decrease + headaches on all sides. @@ -1089,7 +1082,7 @@ pages for more information and options. - Website + Website It's only a sort of an issue of documentation but a good website is quickly becoming an essential part of any free software @@ -1615,30 +1608,26 @@ pages for more information and options. Minimize the number of branches - - Debian may be able to make good use of four or five branches - but it contains gigabytes of software in over 5000 packages - compiled for a 5-6 different architectures. Two is a good - number. Too many branches will confuse your users (I can't - count how many times I had to describe Debian's system when it - only had 2 and sometimes 3 branches!), potential developers - and even yourself. Branches can help but they come at a cost - so use them very sparingly. - + Debian may be able to make good use of four or five + branches but it contains gigabytes of software in over 5000 + packages compiled for a 5-6 different architectures. Two is a + good number. Too many branches will confuse your users (I can't + count how many times I had to describe Debian's system when it + only had 2 and sometimes 3 branches!), potential developers and + even yourself. Branches can help but they come at a cost so use + them very sparingly. Make sure that all your different branches are explained - - As I mentioned in the preceding paragraph, different branches - will confuse your users. Do everything - you can to avoid this by clearly explaining the different - branches in a prominent page on your website and in a Readme - file in the FTP or HTTP - directory. - + As I mentioned in the preceding paragraph, different + branches will confuse your users. Do + everything you can to avoid this by clearly explaining the + different branches in a prominent page on your website and in a + Readme file in the FTP or + HTTP directory. I might also recommend against a mistake that I think Debian @@ -1665,27 +1654,25 @@ pages for more information and options. Make sure all your branches are always available - - Like a lot of document, this should probably should go without - saying but experience has taught me that it's not always - obvious to people. It's a good idea to physically split up - different branches in different directories or directory trees - on your FTP or HTTP - site. Linux accomplishes this by having all the v2.2 and a - v2.3 subdirectory where it is immediately obvious (after you - know their version numbering scheme) which directory is the - most recent stable and the current development - releases. Debian accomplishes this by naming all their - distribution by name and then changing symlinks named - stable, unstable and - frozen to point to which ever distribution (by - name) is in whatever stage. Both methods work and their are - others. In any case, it is important that different branches - are always available, are accessible from consistent - locations, and that different branches are clearly - distinguished from each other so your users know exactly what - they want to be downloading and where to get it. - + Like a lot of document, this should probably should go + without saying but experience has taught me that it's not + always obvious to people. It's a good idea to physically split + up different branches in different directories or directory + trees on your FTP or HTTP + site. Linux accomplishes this by having all the v2.2 and a v2.3 + subdirectory where it is immediately obvious (after you know + their version numbering scheme) which directory is the most + recent stable and the current development releases. Debian + accomplishes this by naming all their distribution by name and + then changing symlinks named stable, + unstable and frozen to point to + which ever distribution (by name) is in whatever stage. Both + methods work and their are others. In any case, it is important + that different branches are always available, are accessible + from consistent locations, and that different branches are + clearly distinguished from each other so your users know + exactly what they want to be downloading and where to get + it. @@ -2181,56 +2168,50 @@ pages for more information and options. alpha releases - - Alpha releases are expected to be unstable, perhaps a little - unsafe, but definitely usable. Alpha versions should have - full functionality and limited testing. They can have known - bugs and kinks that have yet to be worked out. Before sure to - keep in mind that alpha releases are still - releases and people are not going to be expecting - a nightly build from the CVS source. An alpha should work and - have minimal testing and bug fixing already finished. - + Alpha releases are expected to be unstable, perhaps a + little unsafe, but definitely usable. Alpha versions should + have full functionality and limited testing. They can have + known bugs and kinks that have yet to be worked out. Before + sure to keep in mind that alpha releases are still + releases and people are not going to be expecting a + nightly build from the CVS source. An alpha should work and + have minimal testing and bug fixing already finished. beta releases - - Beta releases are general expected to be usable and - slightly unstable, although definitely - not unsafe. Beta releases usually - preclude a full release by under a month. They can contain - small known bugs but no major ones. All major functionality - should be fully implemented although the exact mechanics can - still be worked out. Beta releases are great tool to whet the - appetites of potential users by giving them a very - realistic view of where your project is going in the very - near future and can help keep interest by giving people - something. - + Beta releases are general expected to be usable and + slightly unstable, although definitely + not unsafe. Beta releases usually + preclude a full release by under a month. They can contain + small known bugs but no major ones. All major functionality + should be fully implemented although the exact mechanics can + still be worked out. Beta releases are great tool to whet the + appetites of potential users by giving them a very realistic + view of where your project is going in the very near future + and can help keep interest by giving people + something. development releases - - Development release is much more vague term than - alpha or beta. I usually choose - to reserve the term for discussion of a development - branch. There are other ways to use the term. So many in - fact, that I feel the term has been cheapened. The popular - window manager Enlightenment has - released nothing but development - releases. Most often, the term is used to describe releases - that are not even to alpha or beta stages though and if I - were to release a pre-alpha release in order to keep interest - in my project live, this is probably how I would have to label - it. - + Development release is much more vague term than + alpha or beta. I usually choose + to reserve the term for discussion of a development + branch. There are other ways to use the term. So many in fact, + that I feel the term has been cheapened. The popular window + manager Enlightenment has + released nothing but development + releases. Most often, the term is used to describe releases + that are not even to alpha or beta stages though and if I were + to release a pre-alpha release in order to keep interest in my + project live, this is probably how I would have to label + it. diff --git a/FreeSoftwareProjectManagementHOWTO.sgml b/FreeSoftwareProjectManagementHOWTO.sgml index 66fd9c6..713938b 100644 --- a/FreeSoftwareProjectManagementHOWTO.sgml +++ b/FreeSoftwareProjectManagementHOWTO.sgml @@ -332,6 +332,7 @@ I'd love for this HOWTO to gain the kind of international reach afforded by a translated version. + However, this HOWTO is still young and I have to yet to be contacted about a translation so English is all that is currently @@ -1016,14 +1017,12 @@ pages for more information and options. README or Readme - - A document containing all the basic installation, - compilation, and even basic use instructions that make up - the bare minimum information needed to get the program up and - running. A README is not your chance to be verbose but needs - to be concise and effective. An ideal README is at least 30 - lines long and more no more than 250. - + A document containing all the basic installation, + compilation, and even basic use instructions that make up the + bare minimum information needed to get the program up and + running. A README is not your chance to be verbose but needs + to be concise and effective. An ideal README is at least 30 + lines long and more no more than 250. @@ -1031,18 +1030,16 @@ pages for more information and options. INSTALL or Install - - The INSTALL file should be much shorter than the INSTALL file - and should quickly and concisely describe how to build and - install the program. Usually an install simply instructs the - user to run ./configure; make; make install and touches on - any unusual options that may be necessary. More advanced - users can usually avoid them but it's good practice to at - least glance at the file to understand what can be - expected. For most relatively standard install procedures and - for most programs, INSTALL files are as short as possible are - rarely over 100 lines. - + The INSTALL file should be much shorter than the INSTALL + file and should quickly and concisely describe how to build + and install the program. Usually an install simply instructs + the user to run ./configure; make; make install and touches on + any unusual options that may be necessary. More advanced users + can usually avoid them but it's good practice to at least + glance at the file to understand what can be expected. For + most relatively standard install procedures and for most + programs, INSTALL files are as short as possible are rarely + over 100 lines. @@ -1050,19 +1047,17 @@ pages for more information and options. Changelog, ChangeLog, CHANGELOG, or changelog - - A changelog is a simple file that every well-managed free - software project should include. A changelog is simple the - file that, as its name would imply, logs or documents the - changes to a program. The most simple way to do a changelog - is to simply keep a file with the source code for your - program and add a section to the top of the changelog with - each release describing what has been, changed, fixed, or - added to the program. It's a good idea to post the changelog - onto the website as well because it can help people decide - whether they want or need to upgrade to a newer version or - wait for a more significant upgrade. - + A changelog is a simple file that every well-managed + free software project should include. A changelog is simple + the file that, as its name would imply, logs or documents the + changes to a program. The most simple way to do a changelog is + to simply keep a file with the source code for your program + and add a section to the top of the changelog with each + release describing what has been, changed, fixed, or added to + the program. It's a good idea to post the changelog onto the + website as well because it can help people decide whether they + want or need to upgrade to a newer version or wait for a more + significant upgrade. @@ -1070,17 +1065,15 @@ pages for more information and options. FAQ - - For those of you that don't already - know. FAQ stands for Frequently Asked - Questions and the file is a collection of exactly that. FAQs - are not difficult to make. Simply make a policy that if you - are asked a question or see a question on a mailing list two - or more times, add it the question (and its answer) to your - FAQs. FAQs are more optional than the files listed above but - they can save your time, increase usability, and decrease - headaches on all sides. - + For those of you that don't already + know. FAQ stands for Frequently Asked + Questions and the file is a collection of exactly that. FAQs + are not difficult to make. Simply make a policy that if you + are asked a question or see a question on a mailing list two + or more times, add it the question (and its answer) to your + FAQs. FAQs are more optional than the files listed above but + they can save your time, increase usability, and decrease + headaches on all sides. @@ -1089,7 +1082,7 @@ pages for more information and options. - Website + Website It's only a sort of an issue of documentation but a good website is quickly becoming an essential part of any free software @@ -1615,30 +1608,26 @@ pages for more information and options. Minimize the number of branches - - Debian may be able to make good use of four or five branches - but it contains gigabytes of software in over 5000 packages - compiled for a 5-6 different architectures. Two is a good - number. Too many branches will confuse your users (I can't - count how many times I had to describe Debian's system when it - only had 2 and sometimes 3 branches!), potential developers - and even yourself. Branches can help but they come at a cost - so use them very sparingly. - + Debian may be able to make good use of four or five + branches but it contains gigabytes of software in over 5000 + packages compiled for a 5-6 different architectures. Two is a + good number. Too many branches will confuse your users (I can't + count how many times I had to describe Debian's system when it + only had 2 and sometimes 3 branches!), potential developers and + even yourself. Branches can help but they come at a cost so use + them very sparingly. Make sure that all your different branches are explained - - As I mentioned in the preceding paragraph, different branches - will confuse your users. Do everything - you can to avoid this by clearly explaining the different - branches in a prominent page on your website and in a Readme - file in the FTP or HTTP - directory. - + As I mentioned in the preceding paragraph, different + branches will confuse your users. Do + everything you can to avoid this by clearly explaining the + different branches in a prominent page on your website and in a + Readme file in the FTP or + HTTP directory. I might also recommend against a mistake that I think Debian @@ -1665,27 +1654,25 @@ pages for more information and options. Make sure all your branches are always available - - Like a lot of document, this should probably should go without - saying but experience has taught me that it's not always - obvious to people. It's a good idea to physically split up - different branches in different directories or directory trees - on your FTP or HTTP - site. Linux accomplishes this by having all the v2.2 and a - v2.3 subdirectory where it is immediately obvious (after you - know their version numbering scheme) which directory is the - most recent stable and the current development - releases. Debian accomplishes this by naming all their - distribution by name and then changing symlinks named - stable, unstable and - frozen to point to which ever distribution (by - name) is in whatever stage. Both methods work and their are - others. In any case, it is important that different branches - are always available, are accessible from consistent - locations, and that different branches are clearly - distinguished from each other so your users know exactly what - they want to be downloading and where to get it. - + Like a lot of document, this should probably should go + without saying but experience has taught me that it's not + always obvious to people. It's a good idea to physically split + up different branches in different directories or directory + trees on your FTP or HTTP + site. Linux accomplishes this by having all the v2.2 and a v2.3 + subdirectory where it is immediately obvious (after you know + their version numbering scheme) which directory is the most + recent stable and the current development releases. Debian + accomplishes this by naming all their distribution by name and + then changing symlinks named stable, + unstable and frozen to point to + which ever distribution (by name) is in whatever stage. Both + methods work and their are others. In any case, it is important + that different branches are always available, are accessible + from consistent locations, and that different branches are + clearly distinguished from each other so your users know + exactly what they want to be downloading and where to get + it. @@ -2181,56 +2168,50 @@ pages for more information and options. alpha releases - - Alpha releases are expected to be unstable, perhaps a little - unsafe, but definitely usable. Alpha versions should have - full functionality and limited testing. They can have known - bugs and kinks that have yet to be worked out. Before sure to - keep in mind that alpha releases are still - releases and people are not going to be expecting - a nightly build from the CVS source. An alpha should work and - have minimal testing and bug fixing already finished. - + Alpha releases are expected to be unstable, perhaps a + little unsafe, but definitely usable. Alpha versions should + have full functionality and limited testing. They can have + known bugs and kinks that have yet to be worked out. Before + sure to keep in mind that alpha releases are still + releases and people are not going to be expecting a + nightly build from the CVS source. An alpha should work and + have minimal testing and bug fixing already finished. beta releases - - Beta releases are general expected to be usable and - slightly unstable, although definitely - not unsafe. Beta releases usually - preclude a full release by under a month. They can contain - small known bugs but no major ones. All major functionality - should be fully implemented although the exact mechanics can - still be worked out. Beta releases are great tool to whet the - appetites of potential users by giving them a very - realistic view of where your project is going in the very - near future and can help keep interest by giving people - something. - + Beta releases are general expected to be usable and + slightly unstable, although definitely + not unsafe. Beta releases usually + preclude a full release by under a month. They can contain + small known bugs but no major ones. All major functionality + should be fully implemented although the exact mechanics can + still be worked out. Beta releases are great tool to whet the + appetites of potential users by giving them a very realistic + view of where your project is going in the very near future + and can help keep interest by giving people + something. development releases - - Development release is much more vague term than - alpha or beta. I usually choose - to reserve the term for discussion of a development - branch. There are other ways to use the term. So many in - fact, that I feel the term has been cheapened. The popular - window manager Enlightenment has - released nothing but development - releases. Most often, the term is used to describe releases - that are not even to alpha or beta stages though and if I - were to release a pre-alpha release in order to keep interest - in my project live, this is probably how I would have to label - it. - + Development release is much more vague term than + alpha or beta. I usually choose + to reserve the term for discussion of a development + branch. There are other ways to use the term. So many in fact, + that I feel the term has been cheapened. The popular window + manager Enlightenment has + released nothing but development + releases. Most often, the term is used to describe releases + that are not even to alpha or beta stages though and if I were + to release a pre-alpha release in order to keep interest in my + project live, this is probably how I would have to label + it. -- 2.39.5