From owner-freebsd-doc  Tue Aug  8 10:26:25 2000
Delivered-To: freebsd-doc@freebsd.org
Received: from mta03-svc.ntlworld.com (mta03-svc.ntlworld.com [62.253.162.43])
	by hub.freebsd.org (Postfix) with ESMTP id 6D40A37BDCA
	for <doc@freebsd.org>; Tue,  8 Aug 2000 10:26:05 -0700 (PDT)
	(envelope-from mark@ukug.uk.freebsd.org)
Received: from parish.my.domain ([62.253.89.61]) by mta03-svc.ntlworld.com
          (InterMail vM.4.01.02.27 201-229-119-110) with ESMTP
          id <20000808172558.WEQW16423.mta03-svc.ntlworld.com@parish.my.domain>
          for <doc@freebsd.org>; Tue, 8 Aug 2000 18:25:58 +0100
Received: (from mark@localhost)
	by parish.my.domain (8.9.3/8.9.3) id SAA02423
	for doc@freebsd.org; Tue, 8 Aug 2000 18:25:44 +0100 (BST)
	(envelope-from mark)
Date: Tue, 8 Aug 2000 18:25:44 +0100
From: Mark Ovens <marko@freebsd.org>
To: doc@freebsd.org
Subject: Contradiction in the FDP-Primer?
Message-ID: <20000808182543.G250@parish>
Mime-Version: 1.0
Content-Type: text/plain; charset=iso-8859-1
Content-Disposition: inline
Content-Transfer-Encoding: 8bit
User-Agent: Mutt/1.2.5i
Organization: Total lack of
Sender: owner-freebsd-doc@FreeBSD.ORG
Precedence: bulk
X-Loop: FreeBSD.org

Just been tidying up some markup in the handbook using the FDP primer
as a guide for the correct way to do things and came across what
appears to be contradictions.

10.1.3.2. Special tags

Some tags just don't follow the indenting rules of the previous section; <screen> and <programlisting> should always be
left-aligned.

    <informalexample>
    <programlisting>
    ...
    </programlisting>
    </informalexample>

<informalexample> also should be left-aligned when it wraps a <screen> or <programlisting>.

These examples should be separated from the rest of the content by a blank line before and after.

Yet earlier, in "Example 4-43. <replaceable>", I see:

Use:

    <informalexample>
      <screen>&prompt.user; <userinput>man <replaceable>command</replaceable></userinput></screen>
    </informalexample>

The example above also highlights another apparent contradiction. This
shows the use of <screen> and <userinput> but in "3.1 Overview" it
uses:

More precisely, they need help identifying what is what. You or I can look at

      To remove /tmp/foo use rm(1).

          % rm /tmp/foo

[snip]

The previous example is actually represented in this document like this;

    <para>To remove <filename>/tmp/foo</filename> use &man.rm.1;.</para>
    
    <para><command>rm /tmp/foo</command></para>

So, which is the correct (or preferred) way to show something like

    % rm /tmp/foo

Note I'm not asking about displaying *interactive* stuff such as

     % ls
     file1
     file2
     file3
     % su
     Password:

type of thing as that always uses <screen> and <userinput> to
differentiate between user and program output text.

-- 
		4.4 - The number of the Beastie
________________________________________________________________
51.44°N  FreeBSD - The Power To Serve http://www.freebsd.org
2.057°W  My Webpage http://ukug.uk.freebsd.org/~mark
mailto:marko@freebsd.org                http://www.radan.com



To Unsubscribe: send mail to majordomo@FreeBSD.org
with "unsubscribe freebsd-doc" in the body of the message