Bug 14248

Summary: codify proposed style
Product: Documentation Reporter: nbm <nbm>
Component: Books & ArticlesAssignee: freebsd-doc (Nobody) <doc>
Status: Closed FIXED    
Severity: Affects Only Me    
Priority: Normal    
Version: Latest   
Hardware: Any   
OS: Any   
Attachments:
Description Flags
file.diff none

Description nbm 1999-10-10 16:10:00 UTC
Codify the proposed style into the writing-style chapter of the
fdp-primer.

I've left out the <programlisting>/<screen> stuff, awaiting further
discussion.

Fix: cvs diff: Diffing writing-style
Comment 1 Tim Vanderhoek 1999-10-10 23:18:52 UTC
On Sun, Oct 10, 1999 at 03:09:14PM -0000, nbm@rucus.ru.ac.za wrote:
> 
> +	<para>When a starting tag which cannot contain character data
> +	  directly follows a tag of the type that requires other tags
> +	  within it to use character data, they are on separate lines.
> +	  The second tag should be properly indented.</para>

First quoted line, do you mean "a starting tag which _can_ contain ..."?
Or do I misunderstand?  (In which case this last piece needs an
example!)


> +	<para>When a tag which can contain character data closes
> +	  directly after a tag which cannot contain character data
> +	  closes, they co-exist on the same line.</para>

Although I realize this is how it's currently done, it seems a little
backwards...


-- 
This is my .signature which gets appended to the end of my messages.
Comment 2 Neil Blakey-Milner 1999-10-12 12:45:22 UTC
On Sun 1999-10-10 (18:18), Tim Vanderhoek wrote:
> > +	<para>When a starting tag which cannot contain character data
> > +	  directly follows a tag of the type that requires other tags
> > +	  within it to use character data, they are on separate lines.
> > +	  The second tag should be properly indented.</para>
> 
> First quoted line, do you mean "a starting tag which _can_ contain ..."?
> Or do I misunderstand?  (In which case this last piece needs an
> example!)

I mean which cannot (or do not normally) directly contain character
data, like <informalexample>, <itemizedlist>, <listitem>, and so
forth.  I suppose there should be a name for it - block and inline is
a slightly different distinction though.

Things that directly contain character data, like <para> and <term>
(there must be more) are the other type.

I'll probably have a more coherent patch next week sometime, after
my sysdev is over.

> > +	<para>When a tag which can contain character data closes
> > +	  directly after a tag which cannot contain character data
> > +	  closes, they co-exist on the same line.</para>
> 
> Although I realize this is how it's currently done, it seems a little
> backwards...

Ok, this is what I had in mind:

<para>Ok, here we go!
  <footnote>
    <para>Well, not really, but almost!</para>
  </footnote></para>

I like this way of doing footnotes, but I suppose we'd better make
a decision on it. (see my programming-tools patch)

Similarly:

<para>Somehow the next list is in this para
  <itemizedlist>
    <listitem>
      <para>Survival</para>
    </listitem>
    <listitem>
      <para>Self-actualisation</para>
    </listitem>
  </itemizedlist></para>

Where else would you like to put that closing tag?  I don't like this
way too much either.

Neil
-- 
Neil Blakey-Milner
nbm@rucus.ru.ac.za
Comment 3 nik freebsd_committer freebsd_triage 1999-12-14 17:01:01 UTC
State Changed
From-To: open->closed

Patch applied, modulo a couple of minor changes (CDATA -> RCDATA)