From simon@arthur.nitro.dk  Wed May 21 16:45:09 2003
Return-Path: <simon@arthur.nitro.dk>
Received: from mx1.FreeBSD.org (mx1.freebsd.org [216.136.204.125])
	by hub.freebsd.org (Postfix) with ESMTP id 92A2537B401
	for <FreeBSD-gnats-submit@freebsd.org>; Wed, 21 May 2003 16:45:09 -0700 (PDT)
Received: from arthur.nitro.dk (port324.ds1-khk.adsl.cybercity.dk [212.242.113.79])
	by mx1.FreeBSD.org (Postfix) with ESMTP id 5C5F343F93
	for <FreeBSD-gnats-submit@freebsd.org>; Wed, 21 May 2003 16:45:06 -0700 (PDT)
	(envelope-from simon@arthur.nitro.dk)
Received: by arthur.nitro.dk (Postfix, from userid 1000)
	id AB41810BF81; Thu, 22 May 2003 01:45:04 +0200 (CEST)
Message-Id: <20030521234504.AB41810BF81@arthur.nitro.dk>
Date: Thu, 22 May 2003 01:45:04 +0200 (CEST)
From: Simon L.Nielsen <simon@nitro.dk>
Reply-To: Simon L.Nielsen <simon@nitro.dk>
To: FreeBSD-gnats-submit@freebsd.org
Cc:
Subject: [patch] Cleanup of laptop article
X-Send-Pr-Version: 3.113
X-GNATS-Notify:

>Number:         52547
>Category:       docs
>Synopsis:       [patch] Cleanup of laptop article
>Confidential:   no
>Severity:       non-critical
>Priority:       low
>Responsible:    freebsd-doc
>State:          closed
>Quarter:        
>Keywords:       
>Date-Required:  
>Class:          doc-bug
>Submitter-Id:   current-users
>Arrival-Date:   Wed May 21 16:50:20 PDT 2003
>Closed-Date:    Fri May 23 10:15:58 PDT 2003
>Last-Modified:  Fri May 23 10:20:05 PDT 2003
>Originator:     Simon L. Nielsen
>Release:        FreeBSD 4.8-STABLE i386
>Organization:
>Environment:
>Description:
General cleanup of the laptop article :

* Add id attributes to all sect1 tags
* s/FreeBSD/&os;/g
* Add application tags around XFree86 references
* Minor markup cleanups... Hope they right
* Refer to more files/programs using manual page references
* Remove some redundant words/sentences (inspired by FDP Writing style section)

Note: This article is in need of a whitespace cleanup.
>How-To-Repeat:
>Fix:
--- doc-article-laptop-cleanup.patch begins here ---
Index: article.sgml
===================================================================
RCS file: /home/ncvs/doc/en_US.ISO8859-1/articles/laptop/article.sgml,v
retrieving revision 1.11
diff -u -d -r1.11 article.sgml
--- article.sgml	31 Mar 2003 21:32:37 -0000	1.11
+++ article.sgml	22 May 2003 01:36:51 -0000
@@ -19,14 +19,14 @@
     <pubdate>$FreeBSD: doc/en_US.ISO8859-1/articles/laptop/article.sgml,v 1.11 2003/03/31 21:32:37 keramida Exp $</pubdate>
    
     <abstract>
-      <para>FreeBSD works fine on most laptops, with a few caveats.
-        Some issues specific to running FreeBSD on laptops, relating
+      <para>&os; works fine on most laptops, with a few caveats.
+        Some issues specific to running &os; on laptops, relating
         to different hardware requirements from desktops, are
         discussed below.</para>
     </abstract>
   </articleinfo>
 
-    <para>FreeBSD is often thought of as a server operating system, but
+    <para>&os; is often thought of as a server operating system, but
       it works just fine on the desktop, and if you want to use it on
       your laptop you can enjoy all the usual benefits: systematic
       layout, easy administration and upgrading, the ports/packages
@@ -39,30 +39,30 @@
       Microsoft Windows).  This article aims to discuss some of these
       issues.</para>
 
-  <sect1>    
-    <title>XFree86</title>
+  <sect1 id="xfree86">
+    <title><application>XFree86</application></title>
       
-    <para>Recent versions of XFree86 work with most display adapters
+    <para>Recent versions of <application>XFree86</application> work with most display adapters
       available on laptops these days.  Acceleration may not be
       supported, but a generic SVGA configuration should work.</para>
 
     <para>Check your laptop documentation for which card you have,
-      and check in the XFree86 documentation (or setup program) 
+      and check in the <application>XFree86</application> documentation (or setup program) 
       to see whether it is specifically supported.  If it is not, use
       a generic device (do not go for a name which just looks
-      similar).  In XFree86 version 4, you can try your luck
+      similar).  In <application>XFree86</application> version 4, you can try your luck
       with the command <userinput>XFree86 -configure</userinput>
       which auto-detects a lot of configurations.</para>
 
     <para>The problem often is configuring the monitor.  Common
-      resources for XFree86 focus on CRT monitors; getting a
+      resources for <application>XFree86</application> focus on CRT monitors; getting a
       suitable modeline for an LCD display may be tricky.  You may
       be lucky and not need to specify a modeline, or just need to
       specify suitable HorizSync and VertRefresh ranges.  If that
       does not work, the best option is to check web resources
       devoted to configuring X on laptops (these are often
       linux-oriented sites but it does not matter because both systems
-      use XFree86) and copy a modeline posted by someone for similar 
+      use <application>XFree86</application>) and copy a modeline posted by someone for similar
       hardware.</para>
 
     <para>Most laptops come with two buttons on their pointing
@@ -71,17 +71,15 @@
       simultaneous left-right click in your X configuration to 
       a middle button click with the line</para>
 
-    <programlisting>
-      Option "Emulate3Buttons"
-    </programlisting>
+    <programlisting>Option "Emulate3Buttons"</programlisting>
 
-    <para>in the XF86Config file in the <literal>InputDevice</literal> 
-      section (for XFree86 version 4; for version 3, put just the line 
+    <para>in <filename>XF86Config</filename> in the <literal>InputDevice</literal>
+      section (for <application>XFree86</application> version 4; for version 3, put just the line
       <literal>Emulate3Buttons</literal>, without the quotes, in the 
       <literal>Pointer</literal> section.)</para>
   </sect1> 
 
-  <sect1> 
+  <sect1 id="modems">
     <title>Modems</title>
     <para> 
       Laptops usually come with internal (on-board) modems.
@@ -98,20 +96,20 @@
 
   </sect1> 
 
-  <sect1> 
+  <sect1 id="pccard">
     <title>PCMCIA (PC Card) devices</title>
 
     <para> Most laptops come with PCMCIA (also called PC Card)
-      slots; these are supported fine under FreeBSD.  Look through
-      your boot-up messages (using <command>dmesg</command>) and see whether these were
+      slots; these are supported fine under &os;.  Look through
+      your boot-up messages (using &man.dmesg.8;) and see whether these were
       detected correctly (they should appear as
       <devicename>pccard0</devicename>,
       <devicename>pccard1</devicename> etc on devices like
       <devicename>pcic0</devicename>).</para>
 
-    <para>FreeBSD currently supports 16-bit PCMCIA cards, but not
+    <para>&os; currently supports 16-bit PCMCIA cards, but not
       32-bit (<quote>CardBus</quote>) cards.   A database of supported 
-      cards is in the file <filename>/etc/defaults/pccard.conf</filename>.  
+      cards is in &man.pccard.conf.5;.
       Look through it, and preferably buy cards listed there.  Cards not
       listed may also work as <quote>generic</quote> devices: in 
       particular most modems (16-bit) should work fine, provided they 
@@ -128,39 +126,38 @@
       card, remove irq 5 (otherwise you may experience hangs when you 
       insert a card).  Check also the available memory slots; if your 
       card is not being detected, try changing it to one of the other 
-      allowed values (listed in the manual page &man.pccardc.8;).
+      allowed values (listed in &man.pccardc.8;).
     </para>
 
-    <para>If it is not running already, start the <command>pccardd</command> daemon.
+    <para>If it is not running already, start the &man.pccardd.8; daemon.
       (To enable it at boot time, add
       <programlisting>pccard_enable="YES"</programlisting> to
-      <filename>/etc/rc.conf</filename>.)  Now your cards should be
+      &man.rc.conf.5;).  Now your cards should be
       detected when you insert and remove them, and you should get
       log messages about new devices being enabled.</para>
 
     <para>There have been major changes to the pccard code
       (including ISA routing of interrupts, for machines whose
-      PCI BIOS FreeBSD can not seem to use) before the FreeBSD 4.4
+      PCI BIOS &os; can not seem to use) before the &os; 4.4
       release.  If you have problems, try upgrading your system.</para>
  
   </sect1> 
 
-  <sect1> 
+  <sect1 id="power-management">
 
     <title>Power management</title>
 
     <para>Unfortunately, this is not very reliably supported under
-      FreeBSD.  If you are lucky, some functions may work reliably;
+      &os;.  If you are lucky, some functions may work reliably;
       or they may not work at all.</para>
 
     <para>To enable this, you may need to compile a kernel with
       power management support (<literal>device apm0</literal>) or
       add the option <literal>enable apm0</literal> to 
-      <filename>/boot/loader.conf</filename>, and
-      also enable the apm daemon at boot time (line
+      &man.loader.conf.5;, and
+      also enable the &man.apm.8; daemon at boot time (line
       <literal>apm_enable="YES"</literal> in
-      <filename>/etc/rc.conf</filename>).  The apm commands are
-      listed in the &man.apm.8; manpage.  For instance,
+      &man.rc.conf.5;).  For instance,
       <command>apm -b</command> gives you battery status (or 255 if
       not supported), <command>apm -Z</command> puts the laptop on
       standby, <command>apm -z</command> (or zzz) suspends it.  To
@@ -170,11 +167,11 @@
       in console mode but not under X (that is, the screen does not
       come on again; in that case, switch to a virtual console
       (using Ctrl-Alt-F1 or another function key) and then execute
-      the apm command.
+      the <command>apm</command> command.
     </para>
 
-    <para>The X window system (XFree86) also includes display power
-      management (look at the &man.xset.1; manual page, and search for
+    <para>The X window system (<application>XFree86</application>) also includes display power
+      management (look at &man.xset.1;, and search for
       <quote>dpms</quote> there).  You may want to investigate this.  However, this, 
       too, works inconsistently on laptops: it
       often turns off the display but does not turn off the
--- doc-article-laptop-cleanup.patch ends here ---


>Release-Note:
>Audit-Trail:
State-Changed-From-To: open->closed 
State-Changed-By: blackend 
State-Changed-When: Fri May 23 10:14:30 PDT 2003 
State-Changed-Why:  
I committed a modified version of your patch.  I will fix some remaining 
problems soon.  Thanks! 

http://www.freebsd.org/cgi/query-pr.cgi?pr=52547 

From: Marc Fonvieille <blackend@FreeBSD.org>
To: "Simon L.Nielsen" <simon@nitro.dk>
Cc: FreeBSD-gnats-submit@FreeBSD.org
Subject: Re: docs/52547: [patch] Cleanup of laptop article
Date: Fri, 23 May 2003 19:11:57 +0200

 On Thu, May 22, 2003 at 01:45:04AM +0200, Simon L.Nielsen wrote:
 > General cleanup of the laptop article :
 > 
 > * Add id attributes to all sect1 tags
 
 This is far to be mandatory on a so little article.
 
 > * s/FreeBSD/&os;/g
 
 This tag should be used on new submission, but a full commit does not
 worth since it brings nothing new to the reader.
 
 > * Add application tags around XFree86 references
 > * Minor markup cleanups... Hope they right
 > * Refer to more files/programs using manual page references
 > * Remove some redundant words/sentences (inspired by FDP Writing style section)
 > 
 > Note: This article is in need of a whitespace cleanup.
 > >How-To-Repeat:
 > >Fix:
 > --- doc-article-laptop-cleanup.patch begins here ---
 [...]
 >  
 > -    <programlisting>
 > -      Option "Emulate3Buttons"
 > -    </programlisting>
 > +    <programlisting>Option "Emulate3Buttons"</programlisting>
 
 It's not good: no whitespace/wrapline change with content change.
 And this one is quite useless.
 
 [...]
 > -      cards is in the file <filename>/etc/defaults/pccard.conf</filename>.  
 > +      cards is in &man.pccard.conf.5;.
 
 /etc/defaults/pccard.conf is always up to date, it's not the case of the
 manual page.
 
 >        Look through it, and preferably buy cards listed there.  Cards not
 >        listed may also work as <quote>generic</quote> devices: in 
 >        particular most modems (16-bit) should work fine, provided they 
 > @@ -128,39 +126,38 @@
 >        card, remove irq 5 (otherwise you may experience hangs when you 
 >        insert a card).  Check also the available memory slots; if your 
 >        card is not being detected, try changing it to one of the other 
 > -      allowed values (listed in the manual page &man.pccardc.8;).
 > +      allowed values (listed in &man.pccardc.8;).
 
 manual page was good there.
 
 >      </para>
 >  
 > -    <para>If it is not running already, start the <command>pccardd</command> daemon.
 > +    <para>If it is not running already, start the &man.pccardd.8; daemon.
 >        (To enable it at boot time, add
 >        <programlisting>pccard_enable="YES"</programlisting> to
 > -      <filename>/etc/rc.conf</filename>.)  Now your cards should be
 > +      &man.rc.conf.5;).  Now your cards should be
 
 Well /etc/rc.conf is a better choice there, for obvious reason.
 
 >        detected when you insert and remove them, and you should get
 >        log messages about new devices being enabled.</para>
 >  
 >      <para>There have been major changes to the pccard code
 >        (including ISA routing of interrupts, for machines whose
 > -      PCI BIOS FreeBSD can not seem to use) before the FreeBSD 4.4
 > +      PCI BIOS &os; can not seem to use) before the &os; 4.4
 >        release.  If you have problems, try upgrading your system.</para>
 >   
 >    </sect1> 
 >  
 > -  <sect1> 
 > +  <sect1 id="power-management">
 >  
 >      <title>Power management</title>
 >  
 >      <para>Unfortunately, this is not very reliably supported under
 > -      FreeBSD.  If you are lucky, some functions may work reliably;
 > +      &os;.  If you are lucky, some functions may work reliably;
 >        or they may not work at all.</para>
 >  
 >      <para>To enable this, you may need to compile a kernel with
 >        power management support (<literal>device apm0</literal>) or
 >        add the option <literal>enable apm0</literal> to 
 > -      <filename>/boot/loader.conf</filename>, and
 > -      also enable the apm daemon at boot time (line
 > +      &man.loader.conf.5;, and
 > +      also enable the &man.apm.8; daemon at boot time (line
 
 /boot/loader.conf is not bad here, and &man.apmd.8; seems better.
 
 Marc
>Unformatted:
