From: Mike Swanson Date: Wed, 12 Nov 2014 05:49:44 +0000 (-0800) Subject: FAQ: Apply formatting that got lost in the inital import X-Git-Tag: 0.6~35 X-Git-Url: http://thyrsus.com/gitweb/?a=commitdiff_plain;h=3ac25a1027072b3dea0e65ef2f1abbfacd584d6d;p=src.git FAQ: Apply formatting that got lost in the inital import Eric didn't realize the source was actually AsciiDoc already, so much of the formatting and a few hyperlinks were lost in translation. --- diff --git a/FAQ.asc b/FAQ.asc index 5df2a12..bbcd2ff 100644 --- a/FAQ.asc +++ b/FAQ.asc @@ -1,6 +1,7 @@ = SRC FAQ = version 1.0 +[[why]] == Why SRC instead of $VCS? == Most version control systems today are multi-user, @@ -8,17 +9,18 @@ multi-file, and multi-fork oriented. These are all good features and properties to have, but they neglect the need to maintain simple single-file documents, such as HOWTOs and FAQs, much like the very file you are reading now. There is even a good use-case for small -programs and scripts. Do you presently keep your ~/bin contents under -version control? If not, consider using SRC for them. +programs and scripts. Do you presently keep your `~/bin` contents under +version control? If not, consider using SRC for them. +[[another-vcs]] == $VCS already does single-file version control, why another one? == It is true, other VCSes already fulfill this simple criterion, SCCS -and RCS being some of the earliest examples dating back to the 1970s and -1980s. While SCCS died off due to its proprietary nature, RCS has kept -a niche for itself precisely for single-file projects. In fact, SRC is -built on top of RCS, rather than reimplementing all of the gritty -master file details. +and RCS being some of the earliest examples dating back to the 1970s +and 1980s. While SCCS died off due to its proprietary nature, +https://www.gnu.org/software/rcs[RCS] has kept a niche for itself +precisely for single-file projects. In fact, SRC is built on top of +RCS, rather than reimplementing all of the gritty master file details. The idea that spawned the development of SRC was that it would have five properties characterizing it: @@ -42,28 +44,31 @@ have proven more effective for multi-user projects and wide coordination. Other projects to mold Mercurial and Git for a single-file purpose at -the very least will fail criteria #3 and #5, and often #4 as well. +the _very_ least will fail criteria #3 and #5, and often #4 as well. +[[dvcs-obsoletion]] == Does SRC mean that $DVCS is obsolete? == Absolutely not! SRC and DVCSes serve entirely opposite needs. SRC’s strength is precisely when there is no need nor desire for collaboration or publishing features, when there is only a single file and a single author for a file. In fact, if your script grows into a -full project in its own right, SRC has a 'src fast-export command' that +full project in its own right, SRC has a `src fast-export` command that can be used to jump-start a DVCS repository with the entire existing history intact. SRC might make certain uses of DVCS obsolete. Such as keeping individual documents tucked away in their own directories so that the DVCS can operate (which usually have a special repository directed -named like .hg or .git). Scripts to impose a single-file concept on top -of these systems do not go far enough with respect to the reasons SRC -exists. +named like `.hg` or `.git`). Scripts to impose a single-file concept +on top of these systems do not go <> with +respect to the reasons SRC exists. +[[beginners-vcs]] == Is SRC a good system on which to learn about version control? == +======= -YES! SRC is explicitly designed to have the bare-bones features and +*YES*! SRC is explicitly designed to have the bare-bones features and commands of a modern version control system. Keep in mind that SRC’s strength is single-file documents and projects. If you have loose scripts and documents not presently under any version control, SRC is @@ -73,20 +78,23 @@ If instead you have a large multi-file project, ease yourself into using a DVCS with simple commands, possibly even using SRC’s command set as a guideline for which ones to learn first. You will appreciate having actual changesets that span multiple files in this use -case. Mercurial and Git are the most common, which means they are also -easy to find help for. +case. http://mercurial.selenic.com/[Mercurial] and +http://git-scm.com/[Git] are the most common, which means they are +also easy to find help for. +[[keywords]] == Does SRC have keyword expansion? == -No. When SRC commits a file with RCS on the backend, it uses -kb which +No. When SRC commits a file with RCS on the backend, it uses `-kb` which explicitly disables all kind of expansion, and also allows arbitrary binary files to be stored. Keyword expansion has, in general, not been well-accepted in the VCS world and most modern VCSes do not support it at all. Do not even suggest this feature, it will not be implemented. +[[missing-features]] == Does SRC have $FEATURE? == -If you don’t see it in the "src help" listing, probably not. You are +If you don’t see it in the `src help` listing, probably not. You are certainly free to suggest features, but SRC is developed with extreme conservatism as to what features to implement or not. Remember, single-file, single-user, private VCS. @@ -98,11 +106,12 @@ a DVCS. These can all be hard questions, and if you are in doubt, you may go forth with your request, others may share their own opinions. SRC shines in its simplicity. Extra features is not against this, but -too many can easily creep over into “too complicated” territory. +too many can easily creep over into ``too complicated'' territory. +[[network]] == How well does SRC handle files over the network? == -The answer is either “completely fine” or “not at all”, depending on +The answer is either ``completely fine'' or ``not at all'', depending on what is being asked. :-) SRC makes no special provisions, it operates in the current working @@ -110,15 +119,16 @@ directory whether that is local storage, NFS, CIFS, sshfs, or any other kind of networking file system. As long as the directory tree is mounted on your system, SRC should be able to handle it. +[[status-inconsistency]] == Why doesn’t src status display show the same letters as $VCS? == Consistency with other version control systems is an important way to reduce any kind of surprises while using SRC. Unfortunately, the single-letter codes used for statuses are not identical between VCSes and often conflict with each other over specific meanings. For -example, D means deleted in Subversion and Git, but Mercurial uses R -for that same meaning. Git uses R to mean renamed, while Subversion -uses it to mean replaced. +example, *D* means 'deleted' in Subversion and Git, but Mercurial uses +*R* for that same meaning. Git uses *R* to mean 'renamed', while +Subversion uses it to mean 'replaced'. It is an unfortunate state of affairs. The development philosophy behind SRC is to keep it as un-innovative and unsurprising as @@ -127,6 +137,7 @@ converged on the same meanings for single-letter status codes, SRC needs to settle on its own definitions that may differ from what you are used to. +[[not-a-joke]] == Um. This is a joke, right? == No, though the author admits he did laugh a lot while roughing out the @@ -142,8 +153,8 @@ What *will* be funny is when we implement the back end to talk to SCCS. It won't be difficult, that whole end of the interface is encapsulated in a class... +[[ack]] == Acknowledgments == -Nearly all of this FAQ, except "This is a joke, right?", was written -by Mike Swanson, aka chungy. - +Nearly all of this FAQ, except <>, +was written by Mike Swanson, aka chungy.