Path: blob/main/documentation/content/en/books/fdp-primer/overview/_index.po
18098 views
# SOME DESCRIPTIVE TITLE # Copyright (C) YEAR The FreeBSD Project # This file is distributed under the same license as the FreeBSD Documentation package. # FIRST AUTHOR <EMAIL@ADDRESS>, YEAR. # #, fuzzy msgid "" msgstr "" "Project-Id-Version: FreeBSD Documentation VERSION\n" "POT-Creation-Date: 2025-11-08 16:17+0000\n" "PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" "Last-Translator: FULL NAME <EMAIL@ADDRESS>\n" "Language-Team: LANGUAGE <[email protected]>\n" "Language: \n" "MIME-Version: 1.0\n" "Content-Type: text/plain; charset=UTF-8\n" "Content-Transfer-Encoding: 8bit\n" #. type: YAML Front Matter: description #: documentation/content/en/books/fdp-primer/overview/_index.adoc:1 #, no-wrap msgid "Overview about the FreeBSD Documentation Process" msgstr "" #. type: YAML Front Matter: title #: documentation/content/en/books/fdp-primer/overview/_index.adoc:1 #, no-wrap msgid "Chapter 1. Overview" msgstr "" #. type: Title = #: documentation/content/en/books/fdp-primer/overview/_index.adoc:14 #, no-wrap msgid "Overview" msgstr "" #. type: Plain text #: documentation/content/en/books/fdp-primer/overview/_index.adoc:53 msgid "" "Welcome to the FreeBSD Documentation Project (FDP). Quality documentation " "is crucial to the success of FreeBSD, and we value your contributions very " "highly." msgstr "" #. type: Plain text #: documentation/content/en/books/fdp-primer/overview/_index.adoc:55 msgid "" "This document describes how the FDP is organized, how to write and submit " "documentation, and how to effectively use the available tools." msgstr "" #. type: Plain text #: documentation/content/en/books/fdp-primer/overview/_index.adoc:58 msgid "" "Everyone is welcome to contribute to the FDP. Willingness to contribute is " "the only membership requirement." msgstr "" #. type: Plain text #: documentation/content/en/books/fdp-primer/overview/_index.adoc:60 msgid "This primer shows how to:" msgstr "" #. type: Plain text #: documentation/content/en/books/fdp-primer/overview/_index.adoc:62 msgid "Understand the role of documentation and its place in the ecosystem." msgstr "" #. type: Plain text #: documentation/content/en/books/fdp-primer/overview/_index.adoc:63 msgid "Identify which parts of FreeBSD are maintained by the FDP." msgstr "" #. type: Plain text #: documentation/content/en/books/fdp-primer/overview/_index.adoc:64 msgid "Install the required documentation tools and files." msgstr "" #. type: Plain text #: documentation/content/en/books/fdp-primer/overview/_index.adoc:65 msgid "Make changes to the documentation." msgstr "" #. type: Plain text #: documentation/content/en/books/fdp-primer/overview/_index.adoc:66 msgid "" "Submit changes back for review and inclusion in the FreeBSD documentation." msgstr "" #. type: Title == #: documentation/content/en/books/fdp-primer/overview/_index.adoc:68 #, no-wrap msgid "Documentation in the FreeBSD Ecosystem" msgstr "" #. type: Plain text #: documentation/content/en/books/fdp-primer/overview/_index.adoc:72 msgid "" "All documents are for the benefit of their readers, not their writers or " "caretakers. They should adapt to the reader and not expect the reader to " "adapt to them." msgstr "" #. type: Plain text #: documentation/content/en/books/fdp-primer/overview/_index.adoc:74 msgid "Never blame the reader for:" msgstr "" #. type: Plain text #: documentation/content/en/books/fdp-primer/overview/_index.adoc:76 msgid "being unable to make use of a document easily or at all" msgstr "" #. type: Plain text #: documentation/content/en/books/fdp-primer/overview/_index.adoc:77 msgid "finding a document confusing" msgstr "" #. type: Plain text #: documentation/content/en/books/fdp-primer/overview/_index.adoc:78 msgid "not understanding a document or how to apply it" msgstr "" #. type: Plain text #: documentation/content/en/books/fdp-primer/overview/_index.adoc:79 msgid "" "not finding an explicit answer or successfully bridging gaps (or connecting " "dots) to reason their way to one" msgstr "" #. type: Plain text #: documentation/content/en/books/fdp-primer/overview/_index.adoc:81 msgid "Instead, acknowledge that the document is:" msgstr "" #. type: Plain text #: documentation/content/en/books/fdp-primer/overview/_index.adoc:83 msgid "inaccessible" msgstr "" #. type: Plain text #: documentation/content/en/books/fdp-primer/overview/_index.adoc:84 msgid "confusing" msgstr "" #. type: Plain text #: documentation/content/en/books/fdp-primer/overview/_index.adoc:85 msgid "hard to understand or apply" msgstr "" #. type: Plain text #: documentation/content/en/books/fdp-primer/overview/_index.adoc:86 msgid "incomplete" msgstr "" #. type: Plain text #: documentation/content/en/books/fdp-primer/overview/_index.adoc:88 msgid "Then, make the document:" msgstr "" #. type: Plain text #: documentation/content/en/books/fdp-primer/overview/_index.adoc:90 msgid "more accessible" msgstr "" #. type: Plain text #: documentation/content/en/books/fdp-primer/overview/_index.adoc:91 msgid "less confusing" msgstr "" #. type: Plain text #: documentation/content/en/books/fdp-primer/overview/_index.adoc:92 msgid "clearer" msgstr "" #. type: Plain text #: documentation/content/en/books/fdp-primer/overview/_index.adoc:93 msgid "more complete" msgstr "" #. type: Plain text #: documentation/content/en/books/fdp-primer/overview/_index.adoc:95 msgid "Use the following methods:" msgstr "" #. type: Plain text #: documentation/content/en/books/fdp-primer/overview/_index.adoc:97 msgid "" "apply link:https://webaim.org/intro/#principles[accessibility best " "practices] to correct the problem reported and any similar ones you find" msgstr "" #. type: Plain text #: documentation/content/en/books/fdp-primer/overview/_index.adoc:98 msgid "rework or clarify the confusing structure or language" msgstr "" #. type: Plain text #: documentation/content/en/books/fdp-primer/overview/_index.adoc:99 msgid "add relevant examples to the part that is hard to understand or apply" msgstr "" #. type: Plain text #: documentation/content/en/books/fdp-primer/overview/_index.adoc:100 msgid "fill in the gaps or add the missing stepping stones" msgstr "" #. type: Title == #: documentation/content/en/books/fdp-primer/overview/_index.adoc:102 #, no-wrap msgid "Quick Start" msgstr "" #. type: Plain text #: documentation/content/en/books/fdp-primer/overview/_index.adoc:108 msgid "" "Some preparatory steps must be taken before editing the FreeBSD " "documentation. First, subscribe to the {freebsd-doc}. 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." msgstr "" #. type: Title === #: documentation/content/en/books/fdp-primer/overview/_index.adoc:110 #, no-wrap msgid "FreeBSD installation process" msgstr "" #. type: delimited block = 4 #: documentation/content/en/books/fdp-primer/overview/_index.adoc:115 msgid "" "Install these packages. The `docproj` _meta-port_ installs all the " "applications required to do useful work with the FreeBSD documentation." msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/fdp-primer/overview/_index.adoc:119 #, no-wrap msgid "# pkg install docproj\n" msgstr "" #. type: Plain text #: documentation/content/en/books/fdp-primer/overview/_index.adoc:122 #: documentation/content/en/books/fdp-primer/overview/_index.adoc:196 #: documentation/content/en/books/fdp-primer/overview/_index.adoc:278 msgid "" "Install a local working copy of the documentation from the FreeBSD " "repository in [.filename]#~/doc# (see crossref:working-copy[working-copy,The " "Working Copy])." msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/fdp-primer/overview/_index.adoc:126 #: documentation/content/en/books/fdp-primer/overview/_index.adoc:200 #, no-wrap msgid "% git clone https://git.FreeBSD.org/doc.git ~/doc\n" msgstr "" #. type: Plain text #: documentation/content/en/books/fdp-primer/overview/_index.adoc:129 #: documentation/content/en/books/fdp-primer/overview/_index.adoc:203 #: documentation/content/en/books/fdp-primer/overview/_index.adoc:285 msgid "" "Edit the documentation files that require changes. If a file needs major " "changes, consult the mailing list for input." msgstr "" #. type: Plain text #: documentation/content/en/books/fdp-primer/overview/_index.adoc:132 msgid "" "Review the output and edit the file to fix any problems shown, then rerun " "the command to find any remaining problems. Repeat until all of the errors " "are resolved." msgstr "" #. type: Plain text #: documentation/content/en/books/fdp-primer/overview/_index.adoc:134 #, no-wrap msgid "*_Always_* build and review the changes before submitting them. Running `make` in the `documentation` or `website` subdirectories will generate the documentation in HTML format.\n" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/fdp-primer/overview/_index.adoc:138 #, no-wrap msgid "% make\n" msgstr "" #. type: Plain text #: documentation/content/en/books/fdp-primer/overview/_index.adoc:141 msgid "To reduce compile time, only one language can be compiled:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/fdp-primer/overview/_index.adoc:145 #, no-wrap msgid "% make DOC_LANG=en\n" msgstr "" #. type: Plain text #: documentation/content/en/books/fdp-primer/overview/_index.adoc:148 msgid "" "The build output is stored in [.filename]#~/doc/documentation/public/en/" "articles/# and [.filename]#~/doc/documentation/public/en/books/#." msgstr "" #. type: Plain text #: documentation/content/en/books/fdp-primer/overview/_index.adoc:150 msgid "" "Review the build output and ensure the edits are free from typos, layout " "problems, or errors. If any errors are found during the build process, edit " "the problematic files to fix any issues that show up, then run the build " "command again until all errors are resolved." msgstr "" #. type: Plain text #: documentation/content/en/books/fdp-primer/overview/_index.adoc:152 #: documentation/content/en/books/fdp-primer/overview/_index.adoc:215 #: documentation/content/en/books/fdp-primer/overview/_index.adoc:296 msgid "" "Add all the files with `git add .`, then review the diff with `git diff`. " "For example:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/fdp-primer/overview/_index.adoc:157 #: documentation/content/en/books/fdp-primer/overview/_index.adoc:220 #: documentation/content/en/books/fdp-primer/overview/_index.adoc:301 #, no-wrap msgid "" "% git add .\n" "% git diff --staged\n" msgstr "" #. type: Plain text #: documentation/content/en/books/fdp-primer/overview/_index.adoc:160 #: documentation/content/en/books/fdp-primer/overview/_index.adoc:223 #: documentation/content/en/books/fdp-primer/overview/_index.adoc:304 msgid "" "Make sure that all required files are included, then commit the change to " "your local branch and generate a patch with `git format-patch`" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/fdp-primer/overview/_index.adoc:165 #: documentation/content/en/books/fdp-primer/overview/_index.adoc:228 #: documentation/content/en/books/fdp-primer/overview/_index.adoc:309 #, no-wrap msgid "" "% git commit\n" "% git format-patch origin/main\n" msgstr "" #. type: Plain text #: documentation/content/en/books/fdp-primer/overview/_index.adoc:169 #: documentation/content/en/books/fdp-primer/overview/_index.adoc:232 #: documentation/content/en/books/fdp-primer/overview/_index.adoc:313 msgid "" "Patch generated with `git format-patch` will include author identity and " "email addresses, making it easier for developers to apply (with `git am`) " "and give proper credit." msgstr "" #. type: delimited block = 6 #: documentation/content/en/books/fdp-primer/overview/_index.adoc:174 #: documentation/content/en/books/fdp-primer/overview/_index.adoc:237 #: documentation/content/en/books/fdp-primer/overview/_index.adoc:318 msgid "" "To make it easier for committers to apply the patch on their working copy of " "the documentation tree, please generate the [.filename]#.diff# from the base " "of your documentation tree." msgstr "" #. type: Plain text #: documentation/content/en/books/fdp-primer/overview/_index.adoc:177 msgid "" "In the example above, changes have been made to the *bsdinstall* portion of " "the Handbook." msgstr "" #. type: Plain text #: documentation/content/en/books/fdp-primer/overview/_index.adoc:179 msgid "" "Submit the patch or 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 patch or diff " "file. Finally, use the btn:[Submit Bug] button to submit your diff to the " "problem report system." msgstr "" #. type: Title === #: documentation/content/en/books/fdp-primer/overview/_index.adoc:182 #, no-wrap msgid "GNU/Linux installation process" msgstr "" #. type: Plain text #: documentation/content/en/books/fdp-primer/overview/_index.adoc:189 msgid "" "Install these packages in apt-based systems like Debian or Ubuntu. On other " "GNU/Linux distributions the package names may change. Consult your " "distribution's package manager if in doubt." msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/fdp-primer/overview/_index.adoc:193 #, no-wrap msgid "# apt install hugo ruby-asciidoctor ruby-asciidoctor-pdf ruby-rouge git bmake\n" msgstr "" #. type: Plain text #: documentation/content/en/books/fdp-primer/overview/_index.adoc:206 #: documentation/content/en/books/fdp-primer/overview/_index.adoc:288 msgid "" "Review the output and edit the files to fix any problems shown, then rerun " "the command to find any remaining problems. Repeat until all of the errors " "are resolved." msgstr "" #. type: Plain text #: documentation/content/en/books/fdp-primer/overview/_index.adoc:208 #: documentation/content/en/books/fdp-primer/overview/_index.adoc:290 msgid "" "Always build and test the changes before submitting them. Running `bmake` in " "the `documentation` or `website` subdirectories will generate the " "documentation in HTML format." msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/fdp-primer/overview/_index.adoc:212 #, no-wrap msgid "% bmake run LOCALBASE=/usr\n" msgstr "" #. type: Plain text #: documentation/content/en/books/fdp-primer/overview/_index.adoc:245 #: documentation/content/en/books/fdp-primer/overview/_index.adoc:326 msgid "" "Submit the patch or 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_. " "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. Use the btn:[Add an attachment] button to attach the " "patch or diff file. Finally, use the btn:[Submit Bug] button to submit your " "diff to the problem report system." msgstr "" #. type: Title === #: documentation/content/en/books/fdp-primer/overview/_index.adoc:248 #, no-wrap msgid "macOS(R) installation process" msgstr "" #. type: Plain text #: documentation/content/en/books/fdp-primer/overview/_index.adoc:254 msgid "" "Install these packages using link:https://brew.sh/[Homebrew] and " "link:https://rubygems.org/[RubyGem]." msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/fdp-primer/overview/_index.adoc:258 #, no-wrap msgid "$ brew install hugo ruby git bmake\n" msgstr "" #. type: Plain text #: documentation/content/en/books/fdp-primer/overview/_index.adoc:261 msgid "Add Ruby to the Path." msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/fdp-primer/overview/_index.adoc:269 #, no-wrap msgid "" "$ echo 'export PATH=\"$(brew --prefix ruby)/bin:$PATH\"' >> ~/.zshrc\n" "$ echo 'export PATH=\"$(brew --prefix hugo)/bin:$PATH\"' >> ~/.zshrc\n" "$ echo 'export GEM_PATH=\"$(gem environment gemdir)\"' >> ~/.zshrc\n" "$ echo 'export PATH=\"${GEM_PATH}/bin:$PATH\"' >> ~/.zshrc\n" "$ source ~/.zshrc\n" msgstr "" #. type: Plain text #: documentation/content/en/books/fdp-primer/overview/_index.adoc:271 msgid "Install the rouge package using RubyGem." msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/fdp-primer/overview/_index.adoc:275 #, no-wrap msgid "$ sudo gem install rouge asciidoctor asciidoctor-pdf asciidoctor-epub3\n" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/fdp-primer/overview/_index.adoc:282 #, no-wrap msgid "$ git clone https://git.FreeBSD.org/doc.git ~/doc\n" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/fdp-primer/overview/_index.adoc:294 #, no-wrap msgid "$ bmake run USE_RUBYGEMS=YES RUBY_CMD=\"$(brew --prefix ruby)/bin/ruby\" HUGO_CMD=\"$(brew --prefix hugo)/bin/hugo\"\n" msgstr "" #. type: Title == #: documentation/content/en/books/fdp-primer/overview/_index.adoc:329 #, no-wrap msgid "The FreeBSD Documentation Set" msgstr "" #. type: delimited block = 4 #: documentation/content/en/books/fdp-primer/overview/_index.adoc:332 msgid "The FDP is responsible for four categories of FreeBSD documentation." msgstr "" #. type: delimited block = 4 #: documentation/content/en/books/fdp-primer/overview/_index.adoc:334 msgid "" "_Handbook_: The Handbook is the comprehensive online resource and reference " "for FreeBSD users." msgstr "" #. type: delimited block = 4 #: documentation/content/en/books/fdp-primer/overview/_index.adoc:335 msgid "" "_FAQ_: The FAQ uses a short question and answer format to address questions " "that are frequently asked on the various mailing lists and forums devoted to " "FreeBSD. This format does not permit long and comprehensive answers." msgstr "" #. type: delimited block = 4 #: documentation/content/en/books/fdp-primer/overview/_index.adoc:336 msgid "" "_Manual pages_: The English language system manual pages are usually not " "written by the FDP, as they are part of the base system. However, the FDP " "can reword parts of existing manual pages to make them clearer or to correct " "inaccuracies." msgstr "" #. type: delimited block = 4 #: documentation/content/en/books/fdp-primer/overview/_index.adoc:337 msgid "" "_Web site_: This is the main FreeBSD presence on the web, visible at https://" "www.freebsd.org/[https://www.FreeBSD.org/] and many mirrors around the " "world. The web site is typically a new user's first exposure to FreeBSD." msgstr "" #. type: delimited block = 4 #: documentation/content/en/books/fdp-primer/overview/_index.adoc:340 msgid "" "Translation teams are responsible for translating the Handbook and web site " "into different languages. Manual pages are not translated at present." msgstr "" #. type: delimited block = 4 #: documentation/content/en/books/fdp-primer/overview/_index.adoc:342 msgid "" "Documentation source for the FreeBSD web site, Handbook, and FAQ is " "available in the documentation repository at `https://cgit.freebsd.org/doc/`." msgstr "" #. type: delimited block = 4 #: documentation/content/en/books/fdp-primer/overview/_index.adoc:344 msgid "" "Source for manual pages is available in a separate source repository located " "at `https://cgit.freebsd.org/src/`." msgstr "" #. type: delimited block = 4 #: documentation/content/en/books/fdp-primer/overview/_index.adoc:347 msgid "" "Documentation commit messages are visible with `git log`. Commit messages " "are also archived at link:{dev-commits-doc-all}." msgstr "" #. type: delimited block = 4 #: documentation/content/en/books/fdp-primer/overview/_index.adoc:349 msgid "" "Web frontends to both of these repositories are available at https://" "cgit.freebsd.org/doc/[] and https://cgit.freebsd.org/src/[]." msgstr "" #. type: delimited block = 4 #: documentation/content/en/books/fdp-primer/overview/_index.adoc:353 msgid "" "Many people have written tutorials or how-to articles about FreeBSD. Some " "are stored as part of the FDP files. In other cases, the author has decided " "to keep the documentation separate. The FDP endeavors to provide links to " "as much of this external documentation as possible." msgstr ""