From charon@labs.gr  Mon Oct  1 17:19:24 2001
Return-Path: <charon@labs.gr>
Received: from mailsrv.otenet.gr (mailsrv.otenet.gr [195.170.0.5])
	by hub.freebsd.org (Postfix) with ESMTP id D6FAF37B40D
	for <FreeBSD-gnats-submit@freebsd.org>; Mon,  1 Oct 2001 17:19:22 -0700 (PDT)
Received: from hades.hell.gr (patr530-a222.otenet.gr [212.205.215.222])
	by mailsrv.otenet.gr (8.11.5/8.11.5) with ESMTP id f920JJV12214
	for <FreeBSD-gnats-submit@freebsd.org>; Tue, 2 Oct 2001 03:19:19 +0300 (EEST)
Received: (from charon@localhost)
	by hades.hell.gr (8.11.6/8.11.6) id f91MGw415224;
	Tue, 2 Oct 2001 01:16:58 +0300 (EEST)
	(envelope-from charon)
Message-Id: <200110012216.f91MGw415224@hades.hell.gr>
Date: Tue, 2 Oct 2001 01:16:58 +0300 (EEST)
From: Giorgos Keramidas <charon@labs.gr>
Reply-To: Giorgos Keramidas <charon@labs.gr>
To: FreeBSD-gnats-submit@freebsd.org
Cc:
Subject: request for minor clarification of example in the fdp-primer
X-Send-Pr-Version: 3.113
X-GNATS-Notify:

>Number:         30975
>Category:       docs
>Synopsis:       request for minor clarification of example in the fdp-primer
>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:   Mon Oct 01 17:20:00 PDT 2001
>Closed-Date:    Mon Oct 1 23:00:32 PDT 2001
>Last-Modified:  Mon Oct 01 23:01:09 PDT 2001
>Originator:     Giorgos Keramidas
>Release:        FreeBSD 5.0-CURRENT i386
>Organization:
>Environment:
System: FreeBSD hades.hell.gr 5.0-CURRENT FreeBSD 5.0-CURRENT #5: Tue Sep 4
  19:49:44 EEST 2001 root@hades.hell.gr:/usr/obj/usr/src/sys/CHARON i386

>Description:

	I've been reading the fdp-primer book lately, paying a lot of
	attention to more or less important details.  There is one example of
	building the docs, that I wanted to add a little clarification.  The
	patch shown below describes in more detail the use of the
	FORMATS="..." make variable.
	
	I'm not sure if this is good enough, but here it is :-)

>How-To-Repeat:
>Fix:

--- patch begins here ---
Index: en_US.ISO8859-1/books/fdp-primer/overview/chapter.sgml
===================================================================
RCS file: /home/ncvs/doc/en_US.ISO8859-1/books/fdp-primer/overview/chapter.sgml,v
retrieving revision 1.8
diff -u -r1.8 chapter.sgml
--- en_US.ISO8859-1/books/fdp-primer/overview/chapter.sgml	26 Sep 2001 21:49:28 -0000	1.8
+++ en_US.ISO8859-1/books/fdp-primer/overview/chapter.sgml	1 Oct 2001 22:16:19 -0000
@@ -247,11 +247,31 @@
 	  and convert the document to other formats for review.</para>
 
 	<screen>&prompt.user; <userinput>make lint</userinput>
-&prompt.user; <userinput>make FORMATS=<replaceable>format</replaceable></userinput></screen>
+&prompt.user; <userinput>make FORMATS=<replaceable>format-list</replaceable></userinput></screen>
 
-	<para>Where <replaceable>format</replaceable> is one of
+	<para>Where <replaceable>format-list</replaceable> is one of
 	  <literal>html</literal>, <literal>html-split</literal>,
-	  <literal>txt</literal>, or <literal>rtf</literal></para>
+	  <literal>txt</literal>, or <literal>rtf</literal>,
+          or a space-separated list of more than one of these.
+          Use quotes around the list of formats when you build more
+          than one format in one command.</para>
+
+        <para>For example, to convert the document to
+          <literal>html</literal> only, you would use:</para>
+
+	<screen>&prompt.user; <userinput>make FORMATS=html</userinput></screen>
+
+        <para>But when you want to convert the document to both
+          <literal>html</literal> and <literal>txt</literal> format,
+          you should use either two separate &man.make.1; runs,
+          with:</para>
+
+	<screen>&prompt.user; <userinput>make FORMATS=html</userinput>
+&prompt.user; <userinput>make FORMATS=txt</userinput></screen>
+
+        <para>or, you can do it in one command:</para>
+
+	<screen>&prompt.user; <userinput>make FORMATS="html txt"</userinput></screen>
       </step>
 
       <step>
--- patch ends here ---
>Release-Note:
>Audit-Trail:

From: "Bruce A. Mah" <bmah@FreeBSD.ORG>
To: Giorgos Keramidas <charon@labs.gr>
Cc: FreeBSD-gnats-submit@FreeBSD.ORG
Subject: Re: docs/30975: request for minor clarification of example in the fdp-primer 
Date: Mon, 01 Oct 2001 17:30:40 -0700

 --==_Exmh_-1704657648P
 Content-Type: text/plain; charset=us-ascii
 
 If memory serves me right, Giorgos Keramidas wrote:
 
 > -	<para>Where <replaceable>format</replaceable> is one of
 > +	<para>Where <replaceable>format-list</replaceable> is one of
 >  	  <literal>html</literal>, <literal>html-split</literal>,
 > -	  <literal>txt</literal>, or <literal>rtf</literal></para>
 > +	  <literal>txt</literal>, or <literal>rtf</literal>,
 
 Hmmm...it didn't mention pdf or ps?  KNOWN_FORMATS in doc/share/mk/
 doc.docbook.mk lists several other formats as well, don't know how many 
 of these actually work.
 
 Bruce.
 
 
 
 --==_Exmh_-1704657648P
 Content-Type: application/pgp-signature
 
 -----BEGIN PGP SIGNATURE-----
 Version: GnuPG v1.0.6 (FreeBSD)
 Comment: Exmh version 2.3.1+ 05/14/2001
 
 iD8DBQE7uQqw2MoxcVugUsMRAn7NAJ4teiTskklmNk7ZFCMva8YPtO5D/ACghsmo
 vXeT0lCzTOe/C8VEtzycFKw=
 =reE2
 -----END PGP SIGNATURE-----
 
 --==_Exmh_-1704657648P--

From: Giorgos Keramidas <charon@labs.gr>
To: "Bruce A. Mah" <bmah@FreeBSD.ORG>
Cc: FreeBSD-gnats-submit@FreeBSD.ORG
Subject: Re: docs/30975: request for minor clarification of example in the fdp-primer
Date: Tue, 2 Oct 2001 04:22:03 +0300

 Bruce A. Mah <bmah@FreeBSD.ORG> wrote:
 > If memory serves me right, Giorgos Keramidas wrote:
 > 
 > > -	<para>Where <replaceable>format</replaceable> is one of
 > > +	<para>Where <replaceable>format-list</replaceable> is one of
 > >  	  <literal>html</literal>, <literal>html-split</literal>,
 > > -	  <literal>txt</literal>, or <literal>rtf</literal></para>
 > > +	  <literal>txt</literal>, or <literal>rtf</literal>,
 > 
 > Hmmm...it didn't mention pdf or ps?  KNOWN_FORMATS in doc/share/mk/
 > doc.docbook.mk lists several other formats as well, don't know how many 
 > of these actually work.
 
 No, it does not mention any other formats.  Anyway, a pointer to
 doc.docbook.mk for finding out about those other formats, and an example of
 building multiple formats with FORMATS="x y z" seems more proper.
 Do you want me to update the diff of this PR, to add the reference to
 doc.docbook.mk ?
 
 -giorgos
 

From: bmah@FreeBSD.ORG (Bruce A. Mah)
To: Giorgos Keramidas <charon@labs.gr>
Cc: "Bruce A. Mah" <bmah@FreeBSD.ORG>,
	FreeBSD-gnats-submit@FreeBSD.ORG
Subject: Re: docs/30975: request for minor clarification of example in the fdp-primer 
Date: Mon, 01 Oct 2001 22:03:42 -0700

 If memory serves me right, Giorgos Keramidas wrote:
 
 > No, it does not mention any other formats.  Anyway, a pointer to
 > doc.docbook.mk for finding out about those other formats, and an example of
 > building multiple formats with FORMATS="x y z" seems more proper.
 > Do you want me to update the diff of this PR, to add the reference to
 > doc.docbook.mk ?
 
 Sorry, I was perhaps more terse than I should have been.  It's probably
 fine to just mention PS and PDF as possible formats along with the
 rest....the list of formats rarely changes.
 
 Bruce.
 
 
State-Changed-From-To: open->closed 
State-Changed-By: murray 
State-Changed-When: Mon Oct 1 23:00:32 PDT 2001 
State-Changed-Why:  
I applied the patch and then made the changes suggested in the audit 
trail.  Thanks! 


http://www.FreeBSD.org/cgi/query-pr.cgi?pr=30975 
>Unformatted:
