diff --git a/en_US.ISO8859-1/books/fdp-primer/Makefile b/en_US.ISO8859-1/books/fdp-primer/Makefile --- a/en_US.ISO8859-1/books/fdp-primer/Makefile +++ b/en_US.ISO8859-1/books/fdp-primer/Makefile @@ -22,7 +22,7 @@ SRCS= book.xml SRCS+= overview/chapter.xml SRCS+= tools/chapter.xml -SRCS+= working-copy/chapter.xml +SRCS+= local-clone/chapter.xml SRCS+= structure/chapter.xml SRCS+= doc-build/chapter.xml SRCS+= the-website/chapter.xml diff --git a/en_US.ISO8859-1/books/fdp-primer/book.xml b/en_US.ISO8859-1/books/fdp-primer/book.xml --- a/en_US.ISO8859-1/books/fdp-primer/book.xml +++ b/en_US.ISO8859-1/books/fdp-primer/book.xml @@ -69,6 +69,7 @@ 2018 2019 2020 + 2021 DocEng @@ -260,7 +261,7 @@ &chap.overview; &chap.tools; - &chap.working-copy; + &chap.local-clone; &chap.structure; &chap.doc-build; &chap.the-website; diff --git a/en_US.ISO8859-1/books/fdp-primer/chapters.ent b/en_US.ISO8859-1/books/fdp-primer/chapters.ent --- a/en_US.ISO8859-1/books/fdp-primer/chapters.ent +++ b/en_US.ISO8859-1/books/fdp-primer/chapters.ent @@ -12,7 +12,7 @@ - + diff --git a/en_US.ISO8859-1/books/fdp-primer/docbook-markup/chapter.xml b/en_US.ISO8859-1/books/fdp-primer/docbook-markup/chapter.xml --- a/en_US.ISO8859-1/books/fdp-primer/docbook-markup/chapter.xml +++ b/en_US.ISO8859-1/books/fdp-primer/docbook-markup/chapter.xml @@ -114,9 +114,9 @@ &os; Elements The 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 Git doc repository, or available online starting at http://svnweb.FreeBSD.org/doc/. + xlink:href="https://cgit.FreeBSD.org/doc/">https://cgit.FreeBSD.org/doc/. DocBook <tag>book</tag> 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 + + + + <application>Git</application> 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 -RS Review 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.diff Give 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-handbook Copy 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 pgpkeys Copy 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 @@ - - <literal>$FreeBSD$</literal> - 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 &dollar; entities to avoid - including actual literal dollar signs in the file: - - &dollar;FreeBSD&dollar; - - The &dollar; 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 - &dollar; 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 &dollar; - is used to replace the dollar sign in the translation entered - into the PO editor: - - &dollar;FreeBSD&dollar; - - - - 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 - - - - <application>Subversion</application> 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;