Differential D34099 Diff 103297 documentation/content/en/books/fdp-primer/overview/_index.adoc

Changeset View

Standalone View

documentation/content/en/books/fdp-primer/overview/_index.adoc

	Show First 20 Lines • Show All 58 Lines • ▼ Show 20 Lines

	* Identify which parts of FreeBSD are maintained by the FDP.			* Identify which parts of FreeBSD are maintained by the FDP.
	* Install the required documentation tools and files.			* Install the required documentation tools and files.
	* Make changes to the documentation.			* Make changes to the documentation.
	* Submit changes back for review and inclusion in the FreeBSD documentation.			* Submit changes back for review and inclusion in the FreeBSD documentation.

	[[overview-quick-start]]			[[overview-quick-start]]
	== Quick Start			== Quick Start

				pauamma_gundo.comUnsubmitted Not Done Inline Actions Per https://wiki.freebsd.org/Bugzilla/DosAndDonts, I'd make it "enter a short description of the problem in the _Summary_ field and add _patch_ to the _Keywords_ field". pauamma_gundo.com: Per https://wiki.freebsd.org/Bugzilla/DosAndDonts, I'd make it "enter a short description of…
	Some preparatory steps must be taken before editing the FreeBSD documentation.			Some preparatory steps must be taken before editing the FreeBSD documentation.
				pauamma_gundo.comUnsubmitted Not Done Inline Actions s/the // pauamma_gundo.com: s/the //
	First, subscribe to the {freebsd-doc}.			First, subscribe to the {freebsd-doc}.
	Some team members also interact on the `#bsddocs` IRC channel on http://www.efnet.org/[EFnet].			Some team members also interact on the `#bsddocs` IRC channel on http://www.efnet.org/[EFnet].
	These people can help with questions or problems involving the documentation.			These people can help with questions or problems involving the documentation.

				[[freebsd-installation-process]]
				=== FreeBSD installation process

	[.procedure]			[.procedure]
	====			====
	. Install these packages. The `docproj` _meta-port_ installs all the applications required to do useful work with the FreeBSD documentation.			. Install these packages. The `docproj` _meta-port_ installs all the applications required to do useful work with the FreeBSD documentation.
	+			+
	[source,shell]			[source,shell]
	....			....
	# pkg install docproj			# pkg install docproj
	....			....
	+			+
	. Install a local working copy of the documentation from the FreeBSD repository in [.filename]#~/doc# (see crossref:working-copy[working-copy,The Working Copy]).			. Install a local working copy of the documentation from the FreeBSD repository in [.filename]#~/doc# (see crossref:working-copy[working-copy,The Working Copy]).
				debdrupUnsubmitted Done Inline Actions I don't think this removal of the .filename macro is correct, since this refers to an actual filepath. debdrup: I don't think this removal of the .filename macro is correct, since this refers to an actual…
				pauamma_gundo.comUnsubmitted Done Inline Actions IAWTC. pauamma_gundo.com: IAWTC.
	+			+
	[source,shell]			[source,shell]
	....			....
	% git clone https://git.FreeBSD.org/doc.git ~/doc			% git clone https://git.FreeBSD.org/doc.git ~/doc
	....			....
	+			+
	. Edit the documentation files that require changes. If a file needs major changes, consult the mailing list for input.			. Edit the documentation files that require changes. If a file needs major changes, consult the mailing list for input.
	+			+
	Show All 11 Lines
	+			+
	[source,shell]			[source,shell]
	....			....
	% cd ~/doc			% cd ~/doc
	% git diff > bsdinstall.diff.txt			% git diff > bsdinstall.diff.txt
	....			....
	+			+
	Give the diff file a descriptive name.			Give the diff file a descriptive name.
	In the example above, changes have been made to the [.filename]#bsdinstall# portion of the Handbook.			In the example above, changes have been made to the bsdinstall portion of the Handbook.
				pauamma_gundo.comUnsubmitted Done Inline Actions Get rid of the passive since you're touching that line? Something like "The example above makes changes to the bsdinstall portion of the Handbook, so use that as part of the diff filename." pauamma_gundo.com: Get rid of the passive since you're touching that line? Something like "The example above makes…
				+
	. Submit the diff file using the web-based https://bugs.FreeBSD.org/bugzilla/enter_bug.cgi?product=Documentation[Problem Report] system. If using the web form, enter a Summary of _[patch] short description of problem_. Select the Component `Documentation`. In the Description field, enter a short description of the changes and any important details about them. Use the btn:[Add an attachment] button to attach the diff file. Finally, use the btn:[Submit Bug] button to submit your diff to the problem report system.			. Submit the diff file using the web-based https://bugs.FreeBSD.org/bugzilla/enter_bug.cgi?product=Documentation[Problem Report] system. If using the web form, enter a Summary of _[patch] short description of problem_. Select the Component `Documentation`. In the Description field, enter a short description of the changes and any important details about them. Use the btn:[Add an attachment] button to attach the diff file. Finally, use the btn:[Submit Bug] button to submit your diff to the problem report system.
				debdrupUnsubmitted Done Inline Actions Doesn't this need to be split into one line per sentence. debdrup: Doesn't this need to be split into one line per sentence.
				====

				[[gnu-linux-installation-process]]
				=== GNU/Linux installation process

				[.procedure]
				====
				[TIP]
				======
				Hugo version 0.90 or higher must be used
				======

				. Install these packages in apt-based systems like Debian or Ubuntu.
				pauamma_gundo.comUnsubmitted Done Inline Actions That should be one sentence, not 2. pauamma_gundo.com: That should be one sentence, not 2.
				On other GNU/Linux distributions the package names may change.
				Consult your distribution's package manager if in doubt.
				+
				[source,shell]
				....
				# apt install hugo ruby-asciidoctor ruby-asciidoctor-pdf ruby-rouge git bmake
				....
				+
				. Install a local working copy of the documentation from the FreeBSD repository in [.filename]#~/doc# (see crossref:working-copy[working-copy,The Working Copy]).
				+
				[source,shell]
				....
				% git clone https://git.FreeBSD.org/doc.git ~/doc
				....
				+
				. Edit the documentation files that require changes. If a file needs major changes, consult the mailing list for input.
				+
				Review the output and edit the files to fix any problems shown, then rerun the command to find any remaining problems.
				pauamma_gundo.comUnsubmitted Done Inline Actions "files" maybe? Not sure. pauamma_gundo.com: "files" maybe? Not sure.
				Repeat until all of the errors are resolved.
				+
				. Always build and test the changes before submitting them. Running `bmake` in the top-level directory of the documentation will generate that documentation in HTML format.
				debdrupUnsubmitted Done Inline Actions Is this much emphasis necessary? If it is, should it be in a note or similar disclaimer-like box? debdrup: Is this much emphasis necessary? If it is, should it be in a note or similar disclaimer-like…
				+
				[source,shell]
				....
				% bmake run LOCALBASE=/usr
				....
				+
				. When changes are complete and tested, generate a diff file:
				pauamma_gundo.comUnsubmitted Done Inline Actions I'd remove the scare quotes. pauamma_gundo.com: I'd remove the scare quotes.
				+
				[source,shell]
				....
				% cd ~/doc
				% git diff > bsdinstall.diff
				pauamma_gundo.comUnsubmitted Done Inline Actions Is ".txt" necessary? It may be in the Linux environment, if it fails to recognize file content as MIME type text/x-patch or failing that text/plain. pauamma_gundo.com: Is ".txt" necessary? It may be in the Linux environment, if it fails to recognize file content…
				....
				+
				Give the diff file a descriptive name.
				+
				pauamma_gundo.comUnsubmitted Done Inline Actions Redundant with earlier mention on lines 112-113? If not, I would reword to remove the passive too. pauamma_gundo.com: Redundant with earlier mention on lines 112-113? If not, I would reword to remove the passive…
				. Submit the diff file using the web-based https://bugs.FreeBSD.org/bugzilla/enter_bug.cgi?product=Documentation[Problem Report] system.
				If using the web form, enter a Summary of _short description of problem_.
				pauamma_gundo.comUnsubmitted Done Inline Actions No "[patch]". See https://wiki.freebsd.org/Bugzilla/DosAndDonts. Looks like you made that change in the wrong place (see below). pauamma_gundo.com: No "[patch]". See https://wiki.freebsd.org/Bugzilla/DosAndDonts. Looks like you made that…
				Select the Component `Documentation`.
				In the Description field, enter a short description of the problem in the _Summary_ field and add _patch_ to the _Keywords_ field.
				pauamma_gundo.comUnsubmitted Done Inline Actions That was fine as it was. I was asking for a change in what you ask to enter in the summary field. pauamma_gundo.com: That was fine as it was. I was asking for a change in what you ask to enter in **the summary…
				Use the btn:[Add an attachment] button to attach the diff file.
				Finally, use the btn:[Submit Bug] button to submit your diff to the problem report system.
	====			====

	[[overview-doc]]			[[overview-doc]]
	== The FreeBSD Documentation Set			== The FreeBSD Documentation Set

	The FDP is responsible for four categories of FreeBSD documentation.			The FDP is responsible for four categories of FreeBSD documentation.

	* _Handbook_: The Handbook is the comprehensive online resource and reference for FreeBSD users.			* _Handbook_: The Handbook is the comprehensive online resource and reference for FreeBSD users.
	Show All 20 Lines