diff options
| -rw-r--r-- | src/admin/5_networking.xml | 2 | ||||
| -rw-r--r-- | src/admin/adminbook.xml | 4 | ||||
| -rw-r--r-- | src/charters/0001-org.rst | 214 | ||||
| -rw-r--r-- | src/common/helping_hands.xml | 24 | ||||
| -rw-r--r-- | src/devel/develbook.xml | 6 | ||||
| -rw-r--r-- | src/hcl/1_fullsys.xml | 1 | ||||
| -rw-r--r-- | src/hcl/2_mainboard.xml | 4 | ||||
| -rw-r--r-- | src/hcl/3_disk.xml | 4 | ||||
| -rw-r--r-- | src/hcl/4_net.xml | 4 | ||||
| -rw-r--r-- | src/hcl/hclbook.xml | 6 | ||||
| -rw-r--r-- | src/install/1_begin.xml | 64 | ||||
| -rw-r--r-- | src/install/2_req.xml | 111 | ||||
| -rw-r--r-- | src/install/3_beginning.xml | 78 | ||||
| -rw-r--r-- | src/install/installbook.xml | 12 | ||||
| -rw-r--r-- | src/porting/portguide.xml | 2 | ||||
| -rw-r--r-- | src/pretty.css | 15 |
16 files changed, 485 insertions, 66 deletions
diff --git a/src/admin/5_networking.xml b/src/admin/5_networking.xml index 1febe4b..6cfd944 100644 --- a/src/admin/5_networking.xml +++ b/src/admin/5_networking.xml @@ -7,7 +7,7 @@ <para>The Adélie Linux system uses <firstterm><package>netifrc</package></firstterm> as its network configuration and management system. The netifrc system uses a declarative configuration syntax in a single file, <filename>/etc/conf.d/net</filename>, for ease of administration. All main system network configuration is declared in this file. Some additional configuration may be required for wireless or VPN connections; notably, wireless connections require WPA Supplicant to be configured using either <package>wpa_gui</package> (on computers that use X11), or in the <filename>/etc/wpa_supplicant/wpa_supplicant.conf</filename> file.</para> <para>The default configuration for the Adélie Linux system uses the traditional Linux interface names (such as "eth0", "eth1", and "wlan0"). If you prefer the new "predictable" interface names (such as "enP2p36s15f0" or "wlp9s0"), refer to <xref linkend="crappy_udev_ifs" />.</para> <section> - <title>A netfirc primer</title> + <title>A netifrc primer</title> <para>The netifrc configuration file consists of INI-style configuration variables. For example, <literal>config_eth0="dhcp"</literal> sets the variable <varname>config_eth0</varname> to the value <literal>dhcp</literal>. By default, all interfaces on the system that are enabled will attempt to retrieve a DHCP address. Retrieving a DHCP address requires the <package>dhcpcd</package> package to be installed.</para> <para>To enable a network interface, you must create a symbolic link to <filename>/etc/init.d/net.lo</filename> in <filename class="directory">/etc/init.d</filename> named <filename>net.<replaceable>IFACE</replaceable></filename> where <replaceable>IFACE</replaceable> is the name of the interface. For example, for the interface named <literal>eth0</literal>, you would run <command>ln -s /etc/init.d/net.lo /etc/init.d/net.eth0</command>. Next, you need to add the service to the default runlevel. As noted in <xref linkend="enable_disable_rc" />, you would run <command>rc-update add net.<userinput>IFACE</userinput> default</command> to enable the net.<replaceable>IFACE</replaceable> service. You may then <link linkend="start_stop_rc">start the service</link>, assuming the interface has been configured properly in <filename>/etc/conf.d/net</filename>.</para> <para>To disable a network interface, you must first <link linkend="start_stop_rc">stop it</link>, if it is running. Next, <link linkend="enable_disable_rc">remove it from the default runlevel</link> (<command>rc-update del net.<userinput>IFACE</userinput> default</command>). Finally, remove the symbolic link in <filename class="directory">/etc/init.d</filename>.</para> diff --git a/src/admin/adminbook.xml b/src/admin/adminbook.xml index 0c94bd2..f473369 100644 --- a/src/admin/adminbook.xml +++ b/src/admin/adminbook.xml @@ -1,6 +1,7 @@ <?xml version="1.0" encoding="utf-8"?> <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ + <!ENTITY helping SYSTEM "../common/helping_hands.xml"> <!ENTITY chap1 SYSTEM "1_intro.xml"> <!ENTITY chap2 SYSTEM "2_shell.xml"> <!ENTITY chap3 SYSTEM "3_packages.xml"> @@ -31,7 +32,7 @@ <firstname>Tambra</firstname><surname>Wilcox</surname> <contrib>Copyediting</contrib> </othercredit> - <copyright><year>2018</year><holder>Adélie Linux</holder></copyright> + <copyright><year>2018</year><year>2019</year><holder>Adélie Linux</holder></copyright> </bookinfo> <preface> <title>Preface</title> @@ -41,6 +42,7 @@ <para>Please also ensure that you are comfortable and properly rested before reading this handbook. This will allow you to learn quicker, and be able to recall the information you have learned easier.</para> <para>It is hoped by the author that you find this handbook easy to understand and read. Please feel free to contact me or the Adélie Linux community if you have any suggestions on how to make this handbook better. We'd love to hear from you, and we hope you enjoy using our distribution.</para> <para>– A. Wilcox, 2018</para> + &helping; </preface> &chap1; &chap2; diff --git a/src/charters/0001-org.rst b/src/charters/0001-org.rst new file mode 100644 index 0000000..9e431cb --- /dev/null +++ b/src/charters/0001-org.rst @@ -0,0 +1,214 @@ +=============================================== + Project Organisation Charter for Adélie Linux +=============================================== +:Authors: + * **A. Wilcox** +:Status: + Draft; RFC +:Copyright: + © 2019 Adélie Linux Team. CC BY-NC-ND-SA 4.0. + + + +Introduction +============ + +Adélie Linux is growing and maturing into a full-featured Linux distribution +with many individual contributors, goals, and directions of growth. The +Platform Group, serving as the core contributors of the project, desire an +organisational structure that serves the needs of the community. This +structure shall ensure that people who are new to the community can easily +contribute to the project. This structure shall additionally ensure that our +community's goals can be accomplished swiftly and with proper documentation. + +Adding too much formality to this organisational structure could cause undue +delays and pressure on the community, and could stifle innovation and +creativity. Therefore, most of the structure that this charter proposes is +rooted in the processes that Adélie has already organically grown. We feel +that defining these processes, and refining them into even better processes, is +the best way forward for our community. + +For the purposes of this document, a Committer is a contributor to Adélie Linux +whom has write access to at least one official Adélie Linux Git repository. +The process in which Committers are inaugerated into Adélie Linux is described +in a separate Charter. + + + +Projects +======== + +Our first act in this charter is to define "Projects". A Project is a +collective of contributors working towards a common goal. This goal should be +on-going and clearly defined (see Interest Groups below for one-time tasks). +At least one Committer is required to form a Project. + +All Projects will be assigned a mailing list address, typically adelie-$project +where $project is a unique, short name for the Project. + +Projects will be granted a Web space for any documentation they feel +appropriate. All Projects will be required to maintain a list of Committers +involved in the Project on this Web space. Projects may additionally maintain +a list of frequent non-Committer contributors as well, but they are not +required to do so. + +A Project that relates to packages will have an official designated branch of +packages.git. Non-Committer contributors will create merge requests to this +branch, to be reviewed by a Committer in the Project. Committers in the +Project may either create merge requests to this branch, or commit directly to +this branch. A Project may be listed as the maintainer of any package that is +relevant to it. + +Periodically, it is expected that the Project will want to merge its changes in +to the main Adélie Linux system. This will be accomplished by the Project +opening a merge request to the `master` branch, which will be reviewed by at +least one member of the Platform Group. + + +Creating a Project +------------------ + +A Project may be proposed for creation at any time by a Committer, via sending +an email to the adelie-project@ mailing list. This proposal must be approved +by a simple majority of the Platform Group. + +The Project proposal must contain the name of the project, the desired short +name for the mailing list, and the common goal it wishes to achieve. + +The proposal for a new Project may contain an initial list of members. If so, +each member is expected to respond to the message on the adelie-project@ +mailing list with an ACK. If they do not respond to the message within 48 +hours, they will not be added to the initial roster of members of the Project. + + +Joining and Leaving a Project +----------------------------- + +Projects may describe their own processes for joining and leaving their +respective Project. + +The default process, if a Project does not describe their own, is that any +Committer in a Project may nominate any member of the community to join the +Project. The community member then ACKs this using the Project's preferred +communication medium; either mailing list or IRC channel. If no other +Committer is present in the Project, the member is then added; otherwise, at +least one other Committer must agree. + +A community member may leave a Project for any reason. They must communicate +this desire to a Committer in the Project. + + +Disbanding a Project +-------------------- + +A Project may be disbanded without Platform Group interference if all +Committers assigned to the Project wish it so. + +The Platform Group may disband a project with a three-fourths majority. + +When a Project is disbanded, its mailing list must be made read-only, and its +archives must be retained. The Platform Group may destroy the Project's Web +space only under extenuating circumstances. In the event of destruction, URLs +must be set to return a '410 Gone' response. + + + +Interest Groups +=============== + +Our second act in this charter is to define "Interest Groups". An Interest +Group is a collective of contributors working to complete a single task. This +task should be clearly defined, with a reasonable expectation of completion. + +An Interest Group is more informal than a Project; it will only be assigned a +mailing list if a need for one is demonstrated. Additionally, Interest Groups +related to a package or set of packages will not have an official branch of +packages.git created. It is expected that Interest Groups will work with any +relevant Project(s) to accomplish their packaging tasks. + +Interest Groups will be granted Web space for any documentation they feel +appropriate. Interest Groups, like Projects, shall maintain a list of +affiliated Committers on this Web space. They may, additionally, list +non-Committer regular contributors, though this is not required. + + + +Platform Group +============== + +This charter, as with most of the Adélie Linux system, depends heavily on a +functional Platform Group, which acts as the "root" of the structure. As such, +a formal declaration of the Platform Group's responsibilities is provided in +this section. Additionally, addition and removal of members of the Platform +Group are discussed. + +No current member of ComArb may be a concurrent member of the Platform Group. +Similarly, a member of the Platform Group may not be a concurrent member of +ComArb. + +The Project Lead is additionally the lead of the Platform Group. + + +Responsibilities +---------------- + +The Platform Group maintains the base system packages of Adélie Linux. This +includes the origin of the Platform Group's name: the kernel and toolchain. + +The Platform Group ensures orderly and efficient processes, including those +revolving around Projects and Interest Groups. + +The Platform Group handles addition and removal of Committers. + +The Platform Group determines which CPU architectures will be supported by the +Adélie Linux distribution, and in which tier. + +The Platform Group, being the base project of Adélie Linux, may not be +dissolved under any circumstance. In the event that no members are left in the +Platform Group, all Committers must vote to elect a new Project Lead. The new +Project Lead must win via simple majority of all Committers. + + +Addition +-------- + +Nomination of a new member of the Platform Group may be made by any Committer. +The new member must be an existing Committer with no disciplinary action taken +against them in the past six months. The existing Platform Group will then +hold a vote on the candidate; a simple majority will allow the addition of the +Committer to the Platform Group. + +If the Platform Group does not approve the addition of the Committer to the +Platform Group, they may be overridden by a three-fourths majority of +Committers. + + +Removal +------- + +Expulsion of a member of the Platform Group may be initiated by either a member +of the Platform Group itself, or a member of Community Arbitration. + +A vote on whether to expel the member must be held at least 48 hours after the +expulsion announcement, to avoid emotionally charged voting. During this time, +the member may make a statement if they desire to do so. + +All members of the Platform Group vote except the member being expelled. A +three-fourths majority of members must approve the expulsion. If less than +four members of the Platform Group remain to vote, then the largest possible +supermajority is required to approve the expulsion. + +If the Platform Group does not approve the expulsion, it may be overridden by a +complete approval of the expulsion by every Committer. + + +Voting +------ + +In the event of a Platform Group vote resulting in a tie, the vote of the +current Project Lead will be carried. If the Project Lead is absent, the vote +of the senior-most member of the Platform Group that is present for voting will +be carried. + +Seniority in the Platform Group is based on the time since addition to the +Platform Group; it is not based on total time contributing to the project. diff --git a/src/common/helping_hands.xml b/src/common/helping_hands.xml new file mode 100644 index 0000000..2075fea --- /dev/null +++ b/src/common/helping_hands.xml @@ -0,0 +1,24 @@ +<section> + <title>Helping Hands</title> + <para>The Adélie Linux team is finanically supported by the community, not venture capital. We are deeply grateful to our supporters all around the world.</para> + <para>Want to see your name on this list? <ulink url="https://www.patreon.com/Adelie">Become a supporter of the Helping Hand tier or higher on our Patreon</ulink>.</para> + <itemizedlist spacing="compact"> + <listitem><para>J</para></listitem> + <listitem><para>Kiyoshi Aman</para></listitem> + <listitem><para>Dan Theisen</para></listitem> + <listitem><para>Brandon Bergren</para></listitem> + <listitem><para>Tambra Wilcox</para></listitem> + <listitem><para>Lee Starnes</para></listitem> + <listitem><para>Peter Easton</para></listitem> + <listitem><para>liffy</para></listitem> + <listitem><para>JKW</para></listitem> + <listitem><para>Boundarg</para></listitem> + <listitem><para>Laurent Bercot</para></listitem> + <listitem><para>ardea</para></listitem> + <listitem><para>Max Rees</para></listitem> + <listitem><para>Michael Carden</para></listitem> + <listitem><para>Hal Goldfarb</para></listitem> + <listitem><para>nashimus</para></listitem> + <listitem><para>Eric Stokes</para></listitem> + </itemizedlist> +</section> diff --git a/src/devel/develbook.xml b/src/devel/develbook.xml index 6f8ef97..8619069 100644 --- a/src/devel/develbook.xml +++ b/src/devel/develbook.xml @@ -1,6 +1,7 @@ <?xml version="1.0" encoding="utf-8"?> <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ + <!ENTITY helping SYSTEM "../common/helping_hands.xml"> <!ENTITY chap1 SYSTEM "1_preparing.xml"> <!ENTITY chap2 SYSTEM "2_nonpkg.xml"> <!ENTITY chap3 SYSTEM "3_git.xml"> @@ -16,7 +17,7 @@ <author> <personname><firstname>A.</firstname><surname>Wilcox</surname></personname> </author> - <copyright><year>2017</year><year>2018</year><holder>Adélie Linux</holder></copyright> + <copyright><year>2017</year><year>2018</year><year>2019</year><holder>Adélie Linux</holder></copyright> </bookinfo> <preface> <title>Preface</title> @@ -25,7 +26,8 @@ <para>It is assumed that you, the reader, are familiar with using a terminal or command line interface, the use of Unix commands, and the compilation of software. If you are not yet familiar with these concepts, start with our User's Handbook and Administrator's Handbook, which will assist you in learning them.</para> <para>Please also ensure that you are comfortable and properly rested before reading this handbook. This will allow you to learn quicker, and be able to recall the information you have learned easier.</para> <para>It is hoped that you find this handbook easy to understand and read. Please feel free to contact the Adélie Linux community if you have any suggestions on how to make this handbook better. We'd love to hear from you, and we hope you enjoy using our distribution.</para> - <para>– A. Wilcox, 2018</para> + <para>– A. Wilcox, 2019</para> + &helping; </preface> &chap1; &chap2; diff --git a/src/hcl/1_fullsys.xml b/src/hcl/1_fullsys.xml index 79560e5..cee4e5d 100644 --- a/src/hcl/1_fullsys.xml +++ b/src/hcl/1_fullsys.xml @@ -44,6 +44,7 @@ <title>PMMX (32-bit Intel x86)</title> <itemizedlist> <listitem><para>Compaq Armada e500</para></listitem> + <listitem><para>Lenovo IdeaPad S10</para></listitem> </itemizedlist> </section> <section> diff --git a/src/hcl/2_mainboard.xml b/src/hcl/2_mainboard.xml index cdffd69..b5a477e 100644 --- a/src/hcl/2_mainboard.xml +++ b/src/hcl/2_mainboard.xml @@ -20,6 +20,8 @@ </section> <section> <title>x86_64 (64-bit Intel x86)</title> - <para></para> + <itemizedlist> + <listitem><para>ASUS M2N68-AM PLUS</para></listitem> + </itemizedlist> </section> </chapter> diff --git a/src/hcl/3_disk.xml b/src/hcl/3_disk.xml index eac920d..915dc1f 100644 --- a/src/hcl/3_disk.xml +++ b/src/hcl/3_disk.xml @@ -4,7 +4,9 @@ <para></para> <section> <title>SATA (AHCI)</title> - <para></para> + <itemizedlist> + <listitem><para>Seagate Barracuda ST3500620AS</para></listitem> + </itemizedlist> </section> <section> <title>SCSI</title> diff --git a/src/hcl/4_net.xml b/src/hcl/4_net.xml index fc7e012..0aaf4d8 100644 --- a/src/hcl/4_net.xml +++ b/src/hcl/4_net.xml @@ -11,7 +11,9 @@ </section> <section> <title>Wireless adaptors (WiFi)</title> - <para></para> + <itemizedlist> + <listitem><para>Netgear WG311T</para></listitem> + </itemizedlist> </section> <section> <title>Bluetooth adaptors</title> diff --git a/src/hcl/hclbook.xml b/src/hcl/hclbook.xml index 3d114f0..d21c5ab 100644 --- a/src/hcl/hclbook.xml +++ b/src/hcl/hclbook.xml @@ -1,6 +1,7 @@ <?xml version="1.0" encoding="utf-8"?> <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ + <!ENTITY helping SYSTEM "../common/helping_hands.xml"> <!ENTITY chap1 SYSTEM "1_fullsys.xml"> <!ENTITY chap2 SYSTEM "2_mainboard.xml"> <!ENTITY chap3 SYSTEM "3_disk.xml"> @@ -14,18 +15,19 @@ <author> <personname><firstname>A.</firstname><surname>Wilcox</surname></personname> </author> - <copyright><year>2018</year><holder>Adélie Linux</holder></copyright> + <copyright><year>2018</year><year>2019</year><holder>Adélie Linux</holder></copyright> </bookinfo> <preface> <title>Preface</title> <para>This Hardware Compatibility Handbook is the official list of hardware that was tested to ensure an enjoyable user experience while running the Adélie Linux 1.0 system.</para> <para>Many community members contributed the hardware that they use and test on to the final version of this Handbook. This includes many people on the Adélie IRC channel, and the Adélie mailing lists.</para> <para>Please feel free to contact me or the Adélie Linux community if you have any suggestions on how to make this handbook better, including hardware that is working for you, or hardware listed here that is not functioning correctly. We'd love to hear from you, and we hope you enjoy using our distribution.</para> - <para>– A. Wilcox, 2018</para> + <para>– A. Wilcox, 2019</para> <section> <title>Intellectual property notice</title> <para>The trade names, company names, product names, and other names used to describe hardware in this list remain the sole intellectual property of their rightful owners. The usage of these names on this list are for public information of compatibility with the Adélie Linux distribution only. Display on this list does not represent endorsement of Adélie Linux or its maintainers.</para> </section> + &helping; </preface> &chap1; &chap2; diff --git a/src/install/1_begin.xml b/src/install/1_begin.xml index 2a023fc..a58893a 100644 --- a/src/install/1_begin.xml +++ b/src/install/1_begin.xml @@ -1,37 +1,41 @@ <?xml version="1.0" encoding="utf-8"?> <chapter label="1" id="begin"> <title>Before You Begin</title> - <para>Welcome to the Adélie Linux 1.0 Installation Guide. This guide will describe the process you will use to install Adélie Linux on to a computer.</para> - <para>If you are installing Adélie Linux to your main computer, you may use another device - such as a mobile phone or a friend's laptop, if available - to follow along with this guide. - Additionally, most portions of this guide are available on the installation CD for viewing during installation. Just choose "Help" from any page in the Horizon Installation Wizard.</para> + <para>Welcome to the Adélie Linux 1.0 Installation Handbook. + This Handbook will inform you how to install Adélie Linux on your computer.</para> + <para>If you are installing Adélie Linux on your main computer, you may use another device - such as a mobile phone or a friend's laptop, if available - to reference this Handbook. + Additionally, most of this Handbook is available for reading during installation. + Just choose "Help", or press the <keycap>F1</keycap> key, from any page in the System Installation wizard.</para> <section> - <title>Preparing for the installation</title> + <title>Preparing for Installation</title> <para>Please back up all of your data before beginning installation. - While every effort is made to ensure that the Adélie Linux installation routines are safe and error-free, we cannot guarantee that your data will be preserved once you start the installation. + While every effort has been made to ensure that the Adélie Linux installation system is safe and error-free, we cannot guarantee that your data will be preserved once you start the installation. If you intend on dual-booting your computer with another operating system, such as Mac OS X or Windows, ensure there is adequate disk space available to install Adélie Linux. - You will need up to 1 GB for a standard desktop installation, or at least 300 MB for a server installation.</para> - <para>To install Adélie Linux to a desktop or portable computer, you will need a display capable of at least 800x600 pixel resolution. - Most common desktop displays display in at least this resolution. HiDPI (or "Retina") displays are supported only on the KDE Desktop installation media. + You will need up to 2 GB for a standard desktop installation, or at least 300 MB for a server installation.</para> + <para>To install Adélie Linux on a desktop or portable computer, you will need a graphical display capable of at least an 800x600 pixel resolution. + Most displays support this resolution. + HiDPI (or "Retina") displays are supported only on the Desktop installation media. Please note that the server installation media may render incorrectly, or even not at all, when using HiDPI displays. - You may install server packages using the desktop installation media if you need to use a HiDPI display during server installation.</para> + You may install server packages using the Desktop installation media if you need to use a HiDPI display during server installation.</para> <para>To install Adélie Linux to a server, you will need either a display capable of at least 80x25 text console (720x480), or a supported serial line. - If you are installing via serial line, be sure you know your server's serial line settings. - Most servers default to either 9600 or 57200 baud; Adélie Linux does not reconfigure the serial line, so you will need to know your firmware's default settings.</para> + If you are installing via serial line, be sure to have your server's serial line settings available. + Most servers default to either 9600 or 115200 baud; Adélie Linux does not reconfigure the serial line, so you will need to know your firmware's default settings.</para> <para>If you plan on connecting to the Internet directly from your Adélie Linux computer without using a router (not common), ensure you have your Internet access credentials (typically a username and password) available before starting installation. Adélie Linux supports connecting to most ADSL and dial-up Internet providers using PPP; and cable, T1, and fibre providers using Ethernet. If you use a static IP address (not common), make sure you have your IP address, subnet, and default gateway and nameserver settings before starting installation.</para> - <para>If your computer came with recovery media, we recommend that you have it available in the very unlikely event you have an issue with Adélie Linux, or your hardware has an incompatibility. - This way, you will be able to quickly restore your computer to normal operation.</para> + <para>If your computer came with recovery media, we recommend that you have it available in the very unlikely event you have an issue with Adélie Linux, or your hardware is incompatible. + Having your recovery media will allow you to quickly restore your computer to normal operation.</para> </section> - <section> + <section id="media"> <title>Creating the installation media</title> <para>You will need either:</para> <itemizedlist> - <listitem><para>a <hardware>CD drive</hardware> capable of burning a CD, and a blank CD; or</para></listitem> + <listitem><para>a <hardware>CD drive</hardware> capable of writing (or "burning") a CD, and a blank CD; or</para></listitem> <listitem><para>a blank <hardware>USB flash drive</hardware>.</para></listitem> </itemizedlist> - <para>Download the installation media file from your local Adélie Linux mirror. Follow the instructions on the mirror's site to choose the media file appropriate for your computer. + <para>Download the installation media file from your local Adélie Linux mirror at <ulink url="https://distfiles.adelielinux.org/adelie/">https://distfiles.adelielinux.org/adelie/</ulink>. + Follow the instructions on the mirror's site to choose the media file appropriate for your computer. Then, follow the steps below for your current operating environment.</para> <section> <title>Using Windows</title> @@ -43,15 +47,25 @@ </section> <section> <title>Using Linux or BSD</title> - <para>On Linux or BSD systems, you can use either <command>cdrecord</command> or <command>cdrskin</command> to write the installation image to a CD via the command line. Both commands basically share the same syntax.</para> - <para>For example, to burn the image onto a CD at a speed of 4 and with verbose command output, run <command>cdrecord -v speed=4 <userinput>[image]</userinput></command> or <command>cdrskin -v speed=4 <userinput>[image]</userinput></command>, replacing <userinput>[image]</userinput> with the file name of the image you want to burn to the CD.</para> - <para>If there's only one optical disc drive on your system, it should be auto-detected. If not, find the device name using 'dmesg' or 'lsblk' and specify it using the 'dev' option. For example, if your optical device is <literal>/dev/sr0</literal>, run <command>cdrecord -v dev=/dev/sr0 speed=4 <userinput>[image]</userinput></command>.</para> - <para>To write an installation image to a USB flash drive, you can use the <command>dd</command> command.</para> - <para>First, you'll need to get the name of the target device. This can be done by looking at the output of <command>dmesg</command> or any program that lists available storage devices (such as <command>lsblk</command> on Linux) before and after connecting the drive to the computer.</para> - <para>It's a good idea to double-check if you've got that device name right. Make sure you're using the name of the whole drive (such as, e.g., <literal>/dev/sde</literal>) and not merely that of a partition residing on it (e.g., <literal>/dev/sde1</literal>).</para> - <para>Next, make sure the device is not mounted. Then run the <command>dd</command> command and after that the <command>sync</command> command as shown below, replacing <literal>/dev/sdX</literal> with the actual name of the target device and <literal>adelie.iso</literal> with the file name of the image you want to put onto the flash drive. Running these commands may require superuser privileges.</para> - <para>Beware that this operation will <emphasis>destroy all data</emphasis> still residing on the target device!</para> - <para><command>dd if=adelie.iso of=/dev/sdX bs=4M && sync</command></para> + <para>On Linux or BSD systems, you can use either <command>cdrecord</command> or <command>cdrskin</command> to write the installation image to a CD via the command line. + Both commands share a similar syntax.</para> + <para>For example, to burn the image onto a CD at a speed of 4x and with verbose command output, run + <command>cdrecord -v speed=4 <userinput>[image]</userinput></command> + or + <command>cdrskin -v speed=4 <userinput>[image]</userinput></command>, + replacing <userinput>[image]</userinput> with the file name of the image you want to burn to the CD.</para> + <para>If there is only one optical disc drive on your system, it should be auto-detected. + If you have more than one optical disc drive, find the device name using <command>dmesg</command> or <command>lsblk</command>, and specify it with the <varname>dev</varname> option. + For example, if your optical device is named <literal>/dev/sr0</literal>, run + <command>cdrecord -v dev=/dev/sr0 speed=4 <userinput>[image]</userinput></command>.</para> + <para>To write an installation image to a USB flash drive, you may use the <command>dd</command> command. + You will need to identify the name of the target USB device. + This can be done by examining the output of the <command>dmesg</command> command, or a program that lists available storage devices (such as <command>lsblk</command> on Linux), before and after connecting the drive to the computer.</para> + <para>You should always ensure that you have identified the correct USB device name. Ensure you are using the name of the whole drive (such as <literal>/dev/sde</literal>) and not a partition residing on it (such as <literal>/dev/sde1</literal>).</para> + <para>Ensure the device is not mounted before running the <command>dd</command> command. Please note that running the <command>dd</command> command may require superuser privileges.</para> + <para>Beware that this operation will <emphasis>destroy all data</emphasis> on the target device!</para> + <para><command>dd if=<userinput>adelie.iso</userinput> of=<userinput>/dev/sdX</userinput> bs=4M && sync</command></para> + <para>Replace <literal><userinput>adelie.iso</userinput></literal> with the file name of the image you want to write to the USB media, and <literal><userinput>/dev/sdX</userinput></literal> with the name of the target USB device. Running the <command>sync</command> command after the <command>dd</command> command ensures that all data has been written to the USB media.</para> </section> </section> </chapter> diff --git a/src/install/2_req.xml b/src/install/2_req.xml index fde3f00..8f14692 100644 --- a/src/install/2_req.xml +++ b/src/install/2_req.xml @@ -1,36 +1,93 @@ <?xml version="1.0" encoding="utf-8"?> <chapter label="2" id="requirements"> - <title>System Requirements</title> + <title>System Hardware Requirements for Adélie Linux</title> <para>Ensure that your computer meets the following requirements before installing Adélie Linux. On Windows, you may run the <command>msinfo32</command> program to determine your computer's specifications. On a Macintosh, choose <guimenuitem>About This Mac</guimenuitem> from the <guimenu>Apple</guimenu> menu, and then choose <guibutton>System Report</guibutton> or <guibutton>More Info</guibutton>. </para> - <section> - <title>Intel x86 (32-bit)</title> - <para>You will need at least a Pentium or Celeron compatible CPU, with MMX extensions. This includes most AMD (K5+), Transmeta, VIA, and other x86-compatible CPUs. Speeds of at least 500 MHz are highly recommended for running desktop applications, but speeds as low as 100 MHz may be usable in server mode.</para> - <para>At least 256 MB RAM is required to install the desktop version of Adélie Linux, and at least 512 MB RAM is highly recommended if you plan to run larger applications like Firefox and Thunderbird. At least 40 MB RAM is required to install the server version of Adélie Linux.</para> - <warning><title>Warning</title><para>Using less than 40 MB RAM may cause lock ups or crashes during package installation.</para></warning> - <para>At least 3 GB of disk space is required for a full desktop installation of Adélie Linux. The base server installation of Adélie Linux requires about 300 MB of disk space, not counting additional packages and your data. It is recommended that you have at least 1 GB of disk space for most server roles.</para> + <section id="cpu"> + <title>Processor type and speed requirements</title> + <formalpara id="pmmx"> + <title>Intel x86 (32-bit)</title> + <para>You will need at least <emphasis role="bold">a Pentium or Celeron compatible CPU, with MMX extensions</emphasis>. + This includes most AMD (K5+), Transmeta, VIA, and other x86-compatible CPUs. + A processor speed of <emphasis role="bold">at least 500 MHz</emphasis> is highly recommended for running interactive desktop applications; lower speed may be usable in text-only or server modes.</para> + </formalpara> + <formalpara id="x86_64"> + <title>Intel x86_64 (64-bit)</title> + <para>All Intel and AMD CPUs with 64-bit extensions are supported by the Adélie Linux system.</para> + </formalpara> + <formalpara id="ppc"> + <title>PowerPC (32-bit)</title> + <para>You will need at least <emphasis role="bold">a G3 or later</emphasis> CPU. + The 603 CPU is not supported by this version of Adélie Linux. + A processor speed of <emphasis role="bold">at least 600 MHz</emphasis> is highly recommended for running interactive desktop applications, but all G3 and G4 CPUs are supported. + AltiVec/VMX is not required to run Adélie; however, software titles are increasingly taking advantage of processors with these extensions.</para> + </formalpara> + <formalpara id="ppc64"> + <title>PowerPC (64-bit)</title> + <para>You will need a POWER4+, or 970/970fx, or later generation CPU. You cannot use Adélie Linux on a POWER4 or earlier CPU. The Freescale e5500/e6500 and SPE processors do not have the required AltiVec/VMX extensions, and therefore will also not be able to run the 64-bit Adélie Linux.</para> + </formalpara> + <formalpara id="aarch64"> + <title>AArch64 (64-bit ARM)</title> + <para>All 64-bit ARM processors are supported by the Adélie Linux system; however, some SoCs may need a custom kernel. For more information, see the AArch64 HCL<!-- TODO XXX !! -->.</para> + </formalpara> </section> - <section> - <title>Intel x86_64 (64-bit)</title> - <para>All Intel CPUs that have 64-bit extensions are supported by the Adélie Linux kernel and software distribution.</para> - <para>At least 256 MB RAM is required to install the desktop version of Adélie Linux, and at least 512 MB RAM is highly recommended if you plan to run larger applications like Firefox and Thunderbird. At least 48 MB RAM is required to install the server version of Adélie Linux.</para> - <warning><title>Warning</title><para>Using less than 48 MB RAM may cause lock ups or crashes during package installation.</para></warning> - <para>At least 3 GB of disk space is required for a full desktop installation of Adélie Linux. The base server installation of Adélie Linux requires about 270 MB of disk space, not counting additional packages and your data. It is recommended that you have at least 1 GB of disk space for most server roles.</para> - </section> - <section> - <title>PowerPC (32-bit)</title> - <para>You will need at least a G3 CPU. The 603 series is not supported by this version of Adélie Linux. Speeds of at least 600 MHz are highly recommended for running desktop applications, but all G3 and G4 CPUs are supported. AltiVec/VMX is not required to run Adélie, but some packages may perform much better on systems that have these extensions.</para> - <para>At least 3 GB of disk space is required for a full desktop installation of Adélie Linux. The base server installation of Adélie Linux requires about 200 MB of disk space, not counting additional packages and your data. It is recommended that you have at least 1 GB of disk space for most server roles.</para> - </section> - <section> - <title>PowerPC (64-bit)</title> - <para>You will need a POWER4+, or 970/970fx, or later generation CPU. You cannot use Adélie Linux on a POWER4 or earlier CPU. The Freescale e5500/e6500 and SPE processors do not have the required AltiVec/VMX extensions, and therefore will also not be able to run the 64-bit Adélie Linux.</para> - <para>At least 3 GB of disk space is required for a full desktop installation of Adélie Linux. The base server installation of Adélie Linux requires about 200 MB of disk space, not counting additional packages and your data. It is recommended that you have at least 1 GB of disk space for most server roles.</para> - </section> - <section> - <title>AArch64 (64-bit ARM)</title> - <para>All known 64-bit ARM processors should be able to run Adélie Linux.</para> + <section id="ram_disk"> + <title>Memory and disk space requirements</title> + <para>Memory and disk space requirements depend on the edition of Adélie Linux you wish to use.</para> + <table frame="all"> + <title>Minimum and recommended memory and disk space</title> + <tgroup cols="8" align="left" colsep="1" rowsep="1"> + <colspec colname="dimension"/> + <colspec colname="min_min"/> + <colspec colname="min_rec"/> + <colspec colname="compact_min"/> + <colspec colname="compact_rec"/> + <colspec colname="std_min"/> + <colspec colname="std_rec"/> + <colspec colname="full_min"/> + <colspec colname="full_rec"/> + <thead> + <row> + <entry namest="min_min" nameend="min_rec" align="center">Text-Only</entry> + <entry namest="compact_min" nameend="compact_rec" align="center">Compact</entry> + <entry namest="std_min" nameend="std_rec" align="center">Standard</entry> + <entry namest="full_min" nameend="full_rec" align="center">Full</entry> + </row> + <row> + <entry namest="min_min">Minimum</entry><entry>Recommended</entry> + <entry>Minimum</entry><entry>Recommended</entry> + <entry>Minimum</entry><entry>Recommended</entry> + <entry>Minimum</entry><entry>Recommended</entry> + </row> + </thead> + <tbody> + <row> + <entry>Memory</entry> + <entry>64 MB</entry> + <entry>96 MB</entry> + <entry>192 MB</entry> + <entry>256 MB</entry> + <entry>384 MB</entry> + <entry>1 GB</entry> + <entry>512 MB</entry> + <entry>2 GB</entry> + </row> + <row> + <entry>Disk space</entry> + <entry>350 MB</entry> + <entry>512 MB</entry> + <entry>1.5 GB</entry> + <entry>2 GB</entry> + <entry>4 GB</entry> + <entry>6 GB</entry> + <entry>6 GB</entry> + <entry>10 GB</entry> + </row> + </tbody> + </tgroup> + </table> + <warning><title>Warning</title><para>Using less than 96 MB RAM may cause lock ups or crashes during package installation. For systems with less than 96 MB RAM, it is highly recommended that you use the HorizonScript Executor in Target Mode on a computer with more than 96 MB RAM. For more information, see the section on Target Mode.</para></warning> </section> </chapter> diff --git a/src/install/3_beginning.xml b/src/install/3_beginning.xml new file mode 100644 index 0000000..c658e48 --- /dev/null +++ b/src/install/3_beginning.xml @@ -0,0 +1,78 @@ +<?xml version="1.0" encoding="utf-8"?> +<chapter label="3" id="beginning"> + <title>Beginning Installation</title> + <section id="preparing"> + <title>Preparing for Installation</title> + <para>To successfully install Adélie Linux on your computer, you will need:</para> + <itemizedlist> + <listitem><para>Adélie Linux installation media; either CD or USB flash drive. For more information on creating Adélie Linux installation media, see <xref linkend="media"/>.</para></listitem> + <listitem><para>If you will be installing on an existing computer, a backup copy of any important data on your computer.</para></listitem> + <listitem><para>The desired layout of your hard disk.</para></listitem> + <listitem><para>What you will name your computer.</para></listitem> + <listitem><para>Details about your network connection, if you will be connecting to a network.</para></listitem> + <listitem><para>A sheet of paper to write down your account password.</para></listitem> + </itemizedlist> + <para>Once you have these items collected, you will be ready to install Adélie Linux on your computer.</para> + <section id="prep_backup"> + <title>Backup Data</title> + <para>If your computer has an existing operating environment, you must backup your data before starting Adélie Linux System Installation. + This ensures that you will have a copy of your data in case of a system error during installation. + For more information on how to backup your data, consult your current operating environment's documentation. + On Windows, you may refer to <ulink url="https://support.microsoft.com/en-us/help/17127/windows-back-up-restore">Microsoft Help and Support</ulink>; + on Mac OS X, you may refer to <ulink url="https://support.apple.com/en-us/HT201250">Apple Support</ulink>.</para> + </section> + <section id="prep_partition"> + <title>Determine Hard Disk Layout</title> + <para>If your computer will be exclusively running the Adélie Linux operating environment, and you don't plan on installing other environments, you may skip this section; System Installation can create a disk layout for you automatically.</para> + <para>If you wish to "multi-boot" your computer, running multiple operating environments, you will need to carefully consider the layout of your disk. + If you already have an existing operating environment on your computer, you should perform the partitioning step using the tools of that environment. + Adélie Linux System Installation supports creating new partitions on a disk, but it cannot remove or resize existing partitions. + You may need to consult your existing environment's documentation to determine how to correctly set up a multi-boot environment.</para> + <para>On most computers, Adélie Linux requires only a single partition, which will contain all of your data. + However, on some computers, you may need a separate boot partition, which will contain the boot loader software that your computer uses to start up. + For more information, consult your hardware or firmware documentation, and the Installation Handbook section on disk partitioning.<!-- XXX TODO XREF TO THAT SECTION --></para> + <para>As noted in <xref linkend="ram_disk"/>, the disk space needed for an installation of Adélie Linux will vary based on your desired installation type. + You will also need additional room on your disk for your personal data files.</para> + </section> + <section id="prep_naming"> + <title>Name Your Computer</title> + <para>What's in a name? A lot, when you're choosing the name of your computer. + Your computer's name will be shown on the login screen, in the application launcher, and on the command prompt. + It will additionally identify it to others if you have a home or organisational network. + You should give some thought to what your computer's name will be.</para> + <para>Computer names can contain alphabetical characters (capital and uncapital), numbers, and dashes.</para> + <para>If you are setting up a home network, you should give your computer a descriptive name of where it is located or who's computer it is. + For example, Living-Room-PC or Anna-PC.</para> + <para>If you are connecting to an organisational network, your network administrator will assign your computer a name. + It is important you enter the name exactly as your network administrator provides it.</para> + <para>Even if you're not setting up a home network, you will still need a name for your computer. + System Installation will provide a default name for you.</para> + </section> + <section id="prep_network"> + <title>Gather Networking Details</title> + <para>If you will be connecting to a network or the Internet, you should have your connection's details handy so that you can provide them during the installation.</para> + <para>Virtually all home networks and Internet connections use Dynamic IP addressing via DHCP and/or SLAAC. + In this case, you will be able to use the Automatic option in System Installation.</para> + <para>If your connection uses Static IP addressing, you will need your IP address, network prefix, default gateway, and nameserver addresses.</para> + <para>If you use Wireless networking, you will need the name of your Wireless Access Point (AP) and the passphrase for it. + These details are typically found on a label printed on your router or modem.</para> + <para>If your computer has multiple network interfaces (not common), you should note which interface you will use to connect to the network. + You will only be able to use one network interface for System Installation. + You can configure any other network interfaces after the installation is complete.</para> + </section> + </section> + <section id="booting"> + <title>Booting System Installation</title> + <para></para> + </section> + <section id="navigating"> + <title>Navigating System Installation</title> + <para>The System Installation interface is divided in a series of pages, similar to a paper form. + Each page has a title, a short description of the information needed to proceed, and input fields to collect the information.</para> + <para>When you are finishing filling in the information on a page, continue to the next page by clicking the Continue button at the bottom of the window or by pressing the <keycap>F8</keycap> key. + If you want to go back and review or change information on a previous page, you may go back at any time by clicking the Back button at the bottom of the window or by pressing the <keycap>F6</keycap> key.</para> + <para>If you need more information about an option provided, you may open the Help screen by clicking the Help button in the lower left corner of the window or pressing the <keycap>F1</keycap> key. + You can also gain more information by clicking on the question mark in the title bar of System Installation, and then clicking on a field.</para> + <para>If you decide not to complete the installation procedure, you may stop by clicking the Exit button or by pressing the <keycap>F3</keycap> key.</para> + </section> +</chapter> diff --git a/src/install/installbook.xml b/src/install/installbook.xml index 7556119..2074230 100644 --- a/src/install/installbook.xml +++ b/src/install/installbook.xml @@ -1,8 +1,10 @@ <?xml version="1.0" encoding="utf-8"?> <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ + <!ENTITY helping SYSTEM "../common/helping_hands.xml"> <!ENTITY chap1 SYSTEM "1_begin.xml"> <!ENTITY chap2 SYSTEM "2_req.xml"> + <!ENTITY chap3 SYSTEM "3_beginning.xml"> ]> <book> <bookinfo> @@ -10,18 +12,20 @@ <author> <personname><firstname>A.</firstname><surname>Wilcox</surname></personname> </author> - <copyright><year>2015</year><year>2018</year><holder>Adélie Linux</holder></copyright> + <copyright><year>2015</year><year>2018</year><year>2019</year><holder>Adélie Linux</holder></copyright> </bookinfo> <preface> <title>Preface</title> <para>This Installation Handbook is the full, official documentation for installing Adélie Linux 1.0 on a supported computer, including special architecture-specific notes and a bootstrap installation from another distribution. It was initially drafted with a section outline in 2015, before the distribution itself was even created. It is hoped by the author that you find this handbook easy to understand and read.</para> <para>Many contributed to the final version of the Handbook. This includes <personname><othername>[[sroracle]]</othername></personname> and <personname><othername>smaeul</othername></personname> on the Adélie IRC channel, whom tested the instructions on their machines and reported omissions and corrections. <!-- more.. --></para> - <para>Please feel free to contact me or the Adélie Linux community if you have any suggestions on how to make this handbook better. We'd love to hear from you, and we hope you enjoy using our distribution.</para> - <para>– A. Wilcox, 2018</para> + <para>Please feel free to contact the Adélie Linux community if you have any suggestions on how to make this handbook better. We'd love to hear from you, and we hope you enjoy using our distribution.</para> + <para>– A. Wilcox, 2019</para> + &helping; </preface> &chap1; &chap2; - <!-- <xi:include href="3_install.xml" /> + &chap3; + <!-- <xi:include href="4_options.xml" /> <xi:include href="5_commit.xml" /> <xi:include href="6_notes.xml" /> diff --git a/src/porting/portguide.xml b/src/porting/portguide.xml index 255c411..c5c33ee 100644 --- a/src/porting/portguide.xml +++ b/src/porting/portguide.xml @@ -1,6 +1,7 @@ <?xml version="1.0" encoding="utf-8"?> <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ + <!ENTITY helping SYSTEM "../common/helping_hands.xml"> <!ENTITY chap1 SYSTEM "1_intro.xml"> <!ENTITY chap2 SYSTEM "2_bootstrapping.xml"> <!ENTITY chap3 SYSTEM "3_native.xml"> @@ -36,6 +37,7 @@ Please feel free to contact me or the Adélie Linux community if you have any suggestions on how to make this guide better. We'd love to hear from you, and we hope you enjoy using our distribution.</para> <para>– <personname><firstname>A.</firstname><surname>Wilcox</surname></personname>, 2018</para> + &helping; </preface> &chap1; &chap2; diff --git a/src/pretty.css b/src/pretty.css index 8895690..ef4b94e 100644 --- a/src/pretty.css +++ b/src/pretty.css @@ -8,6 +8,7 @@ body { background: white; box-shadow: 2px 2px 10px 2px rgba(0,0,0,.2); font-family: 'Frank Ruhl Libre', Times, serif; + font-size: 100%; padding: 1em; } @@ -17,7 +18,8 @@ body { h1,h2,h3,h4,h5,h6, div.navheader,div.navfooter, -div.toc,div.list-of-tables,div.list-of-examples { +div.toc,div.list-of-tables,div.list-of-examples, +.keycap { font-family: 'IBM Plex Sans', 'Helvetica Neue', Helvetica, sans-serif; } @@ -72,3 +74,14 @@ code.prompt { em.parameter { font-style: normal; } + +.keycap { + border: 1px solid black; + border-radius: 6px; + box-shadow: 0 0 1px #333; + display: inline-block; + font-size: 14px; + padding: 2px; + text-align: center; + width: 24px; +} |