&os; ElementsThe additional &os; elements are not (currently) in the
- Ports Collection. They are stored in the &os; Subversion
- tree, as head/share/xml/freebsd.dtd.
+ Ports Collection. They are stored in the &os; Git
+ documentation repository, as share/xml/freebsd.dtd.
&os;-specific elements used in the examples below are
clearly marked.
@@ -2669,8 +2669,11 @@
article URL entity, followed by an
optional anchor within the article.
URL entities can be found in
- doc/share/xml/urls.ent.
+ share/xml/urls.ent in your local
+ Git repository for the
+ &os; documentation.
+
Usage for &os; book links:paraRead the link
diff --git a/en_US.ISO8859-1/books/fdp-primer/examples/appendix.xml b/en_US.ISO8859-1/books/fdp-primer/examples/appendix.xml
--- a/en_US.ISO8859-1/books/fdp-primer/examples/appendix.xml
+++ b/en_US.ISO8859-1/books/fdp-primer/examples/appendix.xml
@@ -39,10 +39,10 @@
all the elements that might be desirable to use, particularly in a
document's front matter. For more examples of DocBook markup,
examine the XML source for this and other
- documents available in the Subversion
+ documents available in the Gitdoc repository, or available online starting at
http://svnweb.FreeBSD.org/doc/.
+ xlink:href="https://cgit.FreeBSD.org/doc/">https://cgit.FreeBSD.org/doc/.
DocBook book
diff --git a/en_US.ISO8859-1/books/fdp-primer/local-clone/chapter.xml b/en_US.ISO8859-1/books/fdp-primer/local-clone/chapter.xml
new file mode 100644
--- /dev/null
+++ b/en_US.ISO8859-1/books/fdp-primer/local-clone/chapter.xml
@@ -0,0 +1,214 @@
+
+
+
+ The Local Clone
+
+ The local clone is a copy of the &os;
+ documentation repository made on the local computer.
+ Changes are made to the local clone, tested, and then committed
+ and submitted as patches to be committed to the central
+ repository.
+
+ A clone of the documentation repository can occupy 460 megabytes
+ of disk space. Allow for a full gigabyte of space to have room
+ for local branches, temporary files, and test versions of various output
+ formats.
+
+ Git
+ is used to manage the &os; documentation files. It is obtained by
+ installing the Git
+ package:
+
+ &prompt.root; pkg install git
+
+
+ Documentation and Manual Pages
+
+ &os; documentation is not just books and articles. Manual
+ pages for all the commands and configuration files are also part
+ of the documentation, and part of the FDP's
+ territory. Two repositories are involved:
+ doc for the books and articles, and
+ src for the operating system and manual
+ pages. To edit manual pages, the src
+ repository must be checked out separately.
+
+ Repositories may contain multiple versions of documentation
+ and source code. New modifications are almost always made only
+ to the latest version, called main.
+
+
+
+ Choosing a Directory
+
+ &os; documentation is traditionally stored in
+ /usr/doc/, and system
+ source code with manual pages in
+ /usr/src/. These
+ directory trees are relocatable, and users may want to put the
+ working copies in other locations to avoid interfering with
+ existing information in the main directories. The examples
+ that follow use ~/freebsd-doc
+ and ~/freebsd-src, both
+ subdirectories of the user's home directory.
+
+
+
+ Creating a Local Clone
+
+ A local copy of the central repository is called
+ a clone, and done with
+ git clone. This example clones
+ the central documentation repository:
+
+&prompt.user; mkdir ~/freebsd-doc
+&prompt.user; cd ~/freebsd-doc
+&prompt.user; git clone -o freebsd --config remote.freebsd.fetch='+refs/notes/*:refs/notes/*' https://git.freebsd.org/doc.git .
+&prompt.user; git config --local pull.ff only
+&prompt.user; git config --local merge.ff only
+
+ A clone of the source code to work on manual pages is
+ very similar:
+
+&prompt.user; mkdir ~/freebsd-src
+&prompt.user; cd ~/freebsd-src
+&prompt.user; git clone -o freebsd --config remote.freebsd.fetch='+refs/notes/*:refs/notes/*' https://git.freebsd.org/src.git .
+&prompt.user; git config --local pull.ff only
+&prompt.user; git config --local merge.ff only
+
+
+
+ Updating a Local Clone
+
+ The documents and files in the &os; repository change daily.
+ People modify files and commit changes frequently. Even a short
+ time after an initial cloning, there will already be
+ differences between the local clone and the central &os;
+ repository. To update the local clone with the changes that
+ have been made to the central repository, use
+ the following commands in the directory containing the
+ local clone:
+
+ &prompt.user; cd ~/freebsd-doc
+&prompt.user; git checkout main
+&prompt.user; git fetch freebsd
+&prompt.user; git merge freebsd/main
+
+ Get in the protective habit of using
+ these commands before starting a new series of edits.
+ Someone else may have edited that file very recently, and the
+ local clone will not include the latest changes until it
+ has been updated. Editing the newest version of a file is much
+ easier than trying to combine an older, edited local file with
+ the newer version from the central repository.
+
+
+
+ Creating a New Local Project Branch
+
+ Git relies heavily on local
+ branches for related groups of changes, and it's useful to
+ create one before embarking on a new project, even as small as
+ a single typo fix. This has the advantage of keeping unrelated
+ changes logically separate and making things easier when the
+ time comes to submit your changes for inclusion in the central
+ repository. Use something like the following, with a branch
+ name related to the project:
+
+ &prompt.user; cd ~/freebsd-doc
+&prompt.user; git checkout main
+&prompt.user; git checkout -b branch-for-new-project
+
+
+
+ Reverting Changes
+
+ Sometimes it turns out that changes were
+ not necessary after all, or the writer just wants to start over.
+ Files can be reset to their unchanged form with
+ git reset. For example, to erase the edits
+ made to chapter.xml and reset it to
+ unmodified form:
+
+ &prompt.user; git reset chapter.xml
+
+
+
+ Making a Diff
+
+ After edits to a file or group of files are completed, they
+ must be committed to the local repository clone, then the
+ differences between the local repository clone and the version on
+ the &os; central repository must be collected into a single file for
+ submission. These diff files are produced
+ by redirecting the output of git diff into a
+ file:
+
+ &prompt.user; cd ~/freebsd-doc
+&prompt.user; make clean
+&prompt.user; git commit -a
+&prompt.user; git diff main > doc-fix-spelling.diff
+
+ Give the file a meaningful name that identifies the
+ contents. The example above is for spelling fixes to the whole
+ documentation tree.
+
+ If the diff file is to be submitted with the web
+ Submit
+ a &os; problem report interface, add a
+ .txt extension to give the earnest and
+ simple-minded web form a clue that the contents are plain
+ text.
+
+ Be careful: git diff includes all changes
+ made in the current directory and any subdirectories. If there
+ are files in the project branch with edits that are not ready to
+ be submitted yet, provide a list of only the files that are to
+ be included:
+
+ &prompt.user; cd ~/freebsd-doc
+&prompt.user; make clean
+&prompt.user; git commit -a
+&prompt.user; git diff main -- disks/chapter.xml printers/chapter.xml > disks-printers.diff
+
+
+
+ Git References
+
+ These examples show very basic usage of
+ Git. More detail is available
+ in the Git
+ Book and the Git manual
+ pages.
+
+
diff --git a/en_US.ISO8859-1/books/fdp-primer/overview/chapter.xml b/en_US.ISO8859-1/books/fdp-primer/overview/chapter.xml
--- a/en_US.ISO8859-1/books/fdp-primer/overview/chapter.xml
+++ b/en_US.ISO8859-1/books/fdp-primer/overview/chapter.xml
@@ -81,15 +81,14 @@
Install the
- textproc/docproj meta-package
- and Subversion.
+ textproc/docproj meta-package.
This meta-package installs all of the software needed to
- edit and build &os; documentation. The
- Subversion package is needed to
- obtain a working copy of the documentation and generate
+ edit and build &os; documentation, including the
+ Git package needed to
+ obtain a local clone of the documentation and generate
patches with.
- &prompt.root; pkg install docproj subversion
+ &prompt.root; pkg install docproj
@@ -102,12 +101,23 @@
- Install a local working copy of the documentation from
+ Configure git user name and email address globally if
+ desired.
+
+ &prompt.user; git config --global user.name "Full Name"
+&prompt.user; git config --global user.email me@example.org
+
+
+
+ Install a local clone of the documentation from
the &os; repository in
- ~/doc (see
- ).
+ ~/freebsd-doc (see
+ ).
- &prompt.user; svn checkout https://svn.FreeBSD.org/doc/head ~/doc
+ &prompt.user; git clone -o freebsd --config remote.freebsd.fetch='+refs/notes/*:refs/notes/*' https://git.freebsd.org/doc.git ~/freebsd-doc
+&prompt.user; cd ~/freebsd-doc
+&prompt.user; git config --local pull.ff only
+&prompt.user; git config --local merge.ff only
@@ -133,9 +143,12 @@
- Update the local working copy:
+ Update the local repository clone:
- &prompt.user; svn up ~/doc
+ &prompt.user; cd ~/freebsd-doc
+&prompt.user; git checkout main
+&prompt.user; git fetch freebsd
+&prompt.user; git merge freebsd/main
@@ -151,7 +164,7 @@
After editing, check for problems by running:
- &prompt.user; igor -R filename.xml | less -RS
+ &prompt.user; igor -R filename.xml | less -RSReview the output and edit the file to fix any problems
shown, then rerun the command to find any remaining
@@ -171,11 +184,13 @@
- When changes are complete and tested, generate a
- diff file:
+ When changes are complete and tested, commit locally and
+ generate a diff file:
- &prompt.user; cd ~/doc
-&prompt.user; svn diff > bsdinstall.diff.txt
+ &prompt.user; cd ~/freebsd-doc
+&prompt.user; make clean
+&prompt.user; git commit -a
+&prompt.user; git diff main > /tmp/bsdinstall.diffGive the diff file a descriptive name. In the example
above, changes have been made to the
@@ -247,21 +262,21 @@
Documentation source for the &os; web site, Handbook, and
FAQ is available in the documentation
repository at
- https://svn.FreeBSD.org/doc/.
+ https://git.freebsd.org/doc.git.Source for manual pages is available in a separate
source repository located at
- https://svn.FreeBSD.org/base/.
+ https://git.FreeBSD.org/src.git.
Documentation commit messages are visible with
- svn log. Commit messages are also
- archived at
- &a.svn-doc-all.url;.
+ git log. Commit messages are also
+ archived at
+ &a.dev-commits-doc-all.url;.
Web frontends to both of these repositories are available
- at
+ at
and .
+ xlink:href="https://cgit.FreeBSD.org/src/">.
Many people have written tutorials or how-to articles about
&os;. Some are stored as part of the FDP
diff --git a/en_US.ISO8859-1/books/fdp-primer/po-translations/chapter.xml b/en_US.ISO8859-1/books/fdp-primer/po-translations/chapter.xml
--- a/en_US.ISO8859-1/books/fdp-primer/po-translations/chapter.xml
+++ b/en_US.ISO8859-1/books/fdp-primer/po-translations/chapter.xml
@@ -55,24 +55,32 @@
structure and Makefile must be created or
copied from the English original:
+
+ Create a Git branch for the
+ new translation.
+ &prompt.user; git checkout main
+&prompt.user; git checkout -b Spanish-leap-seconds
+
+
Create a directory for the new translation. The
English article source is in
- ~/doc/en_US.ISO8859-1/articles/leap-seconds/.
+ ~/freebsd-doc/en_US.ISO8859-1/articles/leap-seconds/.
The Spanish translation will go in
- ~/doc/es_ES.ISO8859-1/articles/leap-seconds/.
+ ~/freebsd-doc/es_ES.ISO8859-1/articles/leap-seconds/.
The path is the same except for the name of the language
directory.
- &prompt.user; svn mkdir --parents ~/doc/es_ES.ISO8859-1/articles/leap-seconds/
+ &prompt.user; mkdir -p ~/freebsd-doc/es_ES.ISO8859-1/articles/leap-seconds/Copy the Makefile from the original
document into the translation directory:
- &prompt.user; svn cp ~/doc/en_US.ISO8859-1/articles/leap-seconds/Makefile \
- ~/doc/es_ES.ISO8859-1/articles/leap-seconds/
+ &prompt.user; cp ~/freebsd-doc/en_US.ISO8859-1/articles/leap-seconds/Makefile \
+ ~/freebsd-doc/es_ES.ISO8859-1/articles/leap-seconds/
+&prompt.user; git add ~/freebsd-doc/es_ES.ISO8859-1/articles/leap-seconds/Makefile
@@ -322,7 +330,7 @@
The translations are in subdirectories of the main
documentation directory, here assumed to be
- ~/doc/ as shown in
+ ~/freebsd-doc/ as shown in
. For example, German
translations are located in
~/doc/de_DE.ISO8859-1/, and French
@@ -337,9 +345,9 @@
Combining these directory names gives the complete path to
an article or book. For example, the French translation of the
NanoBSD article is in
- ~/doc/fr_FR.ISO8859-1/articles/nanobsd/,
+ ~/freebsd-doc/fr_FR.ISO8859-1/articles/nanobsd/,
and the Mongolian translation of the Handbook is in
- ~/doc/mn_MN.UTF-8/books/handbook/.
+ ~/freebsd-doc/mn_MN.UTF-8/books/handbook/.A new language directory must be created when translating
a document to a new language. If the language directory already
@@ -367,31 +375,35 @@
~/doc/en_US.ISO8859-1/books/porters-handbook/.
+
+ Create a branch for the new translation.
+
+ &prompt.user; cd ~/freebsd-doc
+&prompt.user; git checkout main
+&prompt.user; git checkout -b Spanish-porters-handbook
+
+
The Spanish language books directory
- ~/doc/es_ES.ISO8859-1/books/ already
+ ~/freebsd-doc/es_ES.ISO8859-1/books/ already
exists, so only a new subdirectory for the Porter's
Handbook is needed:
- &prompt.user; cd ~/doc/es_ES.ISO8859-1/books/
-&prompt.user; svn mkdir porters-handbook
-A porters-handbook
+ &prompt.user; cd ~/freebsd-doc/es_ES.ISO8859-1/books/
+&prompt.user; mkdir porters-handbookCopy the Makefile from the
original book:
- &prompt.user; cd ~/doc/es_ES.ISO8859-1/books/porters-handbook
-&prompt.user; svn cp ~/doc/en_US.ISO8859-1/books/porters-handbook/Makefile .
-A Makefile
+ &prompt.user; cd ~/freebsd-doc/es_ES.ISO8859-1/books/porters-handbook
+&prompt.user; cp ~/freebsd-doc/en_US.ISO8859-1/books/porters-handbook/Makefile .Modify the contents of the
Makefile to only expect a single
book.xml:#
-# $FreeBSD$
-#
# Build the FreeBSD Porter's Handbook.
#
@@ -453,23 +465,29 @@
~/doc/en_US.ISO8859-1/articles/pgpkeys/.
+
+ Create a Git branch for the
+ new translation.
+ &prompt.user; cd ~/freebsd-doc
+&prompt.user; git checkout main
+&prompt.user; git checkout -b French-pgpkeys
+
+
The French language article directory
- ~/doc/fr_FR.ISO8859-1/articles/
+ ~/freebsd-doc/fr_FR.ISO8859-1/articles/
already exists, so only a new subdirectory for the
PGP Keys article is needed:
- &prompt.user; cd ~/doc/fr_FR.ISO8859-1/articles/
-&prompt.user; svn mkdir pgpkeys
-A pgpkeys
+ &prompt.user; cd ~/freebsd-doc/fr_FR.ISO8859-1/articles/
+&prompt.user; mkdir pgpkeysCopy the Makefile from the
original article:
- &prompt.user; cd ~/doc/fr_FR.ISO8859-1/articles/pgpkeys
-&prompt.user; svn cp ~/doc/en_US.ISO8859-1/articles/pgpkeys/Makefile .
-A Makefile
+ &prompt.user; cd ~/freebsd-doc/fr_FR.ISO8859-1/articles/pgpkeys
+&prompt.user; cp ~/freebsd-doc/en_US.ISO8859-1/articles/pgpkeys/Makefile .Check the contents of the
Makefile. As this is a simple
@@ -479,8 +497,6 @@
version control system when this file is committed.#
-# $FreeBSD$
-#
# Article: PGP Keys
DOC?= article
@@ -548,7 +564,7 @@
es_ES.po as shown in
.
- &prompt.user; cd ~/doc/es_ES.ISO8859-1/books/porters-handbook
+ &prompt.user; cd ~/freebsd-doc/es_ES.ISO8859-1/books/porters-handbook
&prompt.user; make po
@@ -653,38 +669,6 @@
-
- $FreeBSD$
- Strings
-
- The $FreeBSD$ version strings used in
- files require special handling. In examples like
- , these
- strings are not meant to be expanded. The English documents
- use $ entities to avoid
- including actual literal dollar signs in the file:
-
- $FreeBSD$
-
- The $ entities are not seen
- as dollar signs by the version control system and so the
- string is not expanded into a version string.
-
- When a PO file is created, the
- $ entities used in examples are
- replaced with actual dollar signs. The resulting literal
- $FreeBSD$ string will be
- wrongly expanded by the version control system when the file
- is committed.
-
- The same technique as used in the English documents can be
- used in the translation. The $
- is used to replace the dollar sign in the translation entered
- into the PO editor:
-
- $FreeBSD$
-
-
-
- The Working Copy
-
- The working copy is a copy of the &os;
- repository documentation tree downloaded onto the local computer.
- Changes are made to the local working copy, tested, and then
- submitted as patches to be committed to the main
- repository.
-
- A full copy of the documentation tree can occupy 700 megabytes
- of disk space. Allow for a full gigabyte of space to have room
- for temporary files and test versions of various output
- formats.
-
- Subversion
- is used to manage the &os; documentation files. It is obtained by
- installing the Subversion
- package:
-
- &prompt.root; pkg install subversion
-
-
- Documentation and Manual Pages
-
- &os; documentation is not just books and articles. Manual
- pages for all the commands and configuration files are also part
- of the documentation, and part of the FDP's
- territory. Two repositories are involved:
- doc for the books and articles, and
- base for the operating system and manual
- pages. To edit manual pages, the base
- repository must be checked out separately.
-
- Repositories may contain multiple versions of documentation
- and source code. New modifications are almost always made only
- to the latest version, called head.
-
-
-
- Choosing a Directory
-
- &os; documentation is traditionally stored in
- /usr/doc/, and system
- source code with manual pages in
- /usr/src/. These
- directory trees are relocatable, and users may want to put the
- working copies in other locations to avoid interfering with
- existing information in the main directories. The examples
- that follow use ~/doc
- and ~/src, both
- subdirectories of the user's home directory.
-
-
-
- Checking Out a Copy
-
- A download of a working copy from the repository is called
- a checkout, and done with
- svn checkout. This example checks out a
- copy of the latest version (head) of
- the main documentation tree:
-
- &prompt.user; svn checkout https://svn.FreeBSD.org/doc/head ~/doc
-
- A checkout of the source code to work on manual pages is
- very similar:
-
- &prompt.user; svn checkout https://svn.FreeBSD.org/base/head ~/src
-
-
-
- Updating a Working Copy
-
- The documents and files in the &os; repository change daily.
- People modify files and commit changes frequently. Even a short
- time after an initial checkout, there will already be
- differences between the local working copy and the main &os;
- repository. To update the local version with the changes that
- have been made to the main repository, use
- svn update on the directory containing the
- local working copy:
-
- &prompt.user; svn update ~/doc
-
- Get in the protective habit of using
- svn update before editing document files.
- Someone else may have edited that file very recently, and the
- local working copy will not include the latest changes until it
- has been updated. Editing the newest version of a file is much
- easier than trying to combine an older, edited local file with
- the newer version from the repository.
-
-
-
- Reverting Changes
-
- Sometimes it turns out that changes were
- not necessary after all, or the writer just wants to start over.
- Files can be reset to their unchanged form with
- svn revert. For example, to erase the edits
- made to chapter.xml and reset it to
- unmodified form:
-
- &prompt.user; svn revert chapter.xml
-
-
-
- Making a Diff
-
- After edits to a file or group of files are completed, the
- differences between the local working copy and the version on
- the &os; repository must be collected into a single file for
- submission. These diff files are produced
- by redirecting the output of svn diff into a
- file:
-
- &prompt.user; cd ~/doc
-&prompt.user; svn diff > doc-fix-spelling.diff
-
- Give the file a meaningful name that identifies the
- contents. The example above is for spelling fixes to the whole
- documentation tree.
-
- If the diff file is to be submitted with the web
- Submit
- a &os; problem report interface, add a
- .txt extension to give the earnest and
- simple-minded web form a clue that the contents are plain
- text.
-
- Be careful: svn diff includes all changes
- made in the current directory and any subdirectories. If there
- are files in the working copy with edits that are not ready to
- be submitted yet, provide a list of only the files that are to
- be included:
-
- &prompt.user; cd ~/doc
-&prompt.user; svn diff disks/chapter.xml printers/chapter.xml > disks-printers.diff
-
-
-
- Subversion References
-
- These examples show very basic usage of
- Subversion. More detail is available
- in the Subversion
- Book and the Subversion
- documentation.
-
-
diff --git a/en_US.ISO8859-1/books/fdp-primer/writing-style/chapter.xml b/en_US.ISO8859-1/books/fdp-primer/writing-style/chapter.xml
--- a/en_US.ISO8859-1/books/fdp-primer/writing-style/chapter.xml
+++ b/en_US.ISO8859-1/books/fdp-primer/writing-style/chapter.xml
@@ -197,12 +197,12 @@
For example, commands:
- Wrong: Use the svn command to
+ Wrong: Use the git command to
update sources.
- Right: Use svn to update
+ Right: Use git to update
sources.
@@ -527,6 +527,17 @@
file system
+
+ Git
+
+ applicationGitapplication
+ Do not refer to the Git application as
+ GIT in upper case. To refer to the
+ command, use commandgitcommand.
+
+
IPsec
@@ -574,17 +585,6 @@
varnamestderrvarname
-
- Subversion
-
- applicationSubversionapplication
- Do not refer to the Subversion application as
- SVN in upper case. To refer to the
- command, use commandsvncommand.
-
-
&unix;&unix;