docutils-develop

[Docutils-develop] Forcing line breaks

[Adam C. <ad...@ch...>]

Hi.

Is there any way to force line breaks? Example of usage::

  :Name:    Adam Chodorowski
  :Address: The Street
            11111 The Town
            The Country
  :Phone:   +11-111111

This looks very ugly if you run it through docutils, so the ability to force
line breaks (at the obvious places) would be very useful. I looked through the
documentation, but couldn't find any mention of it...

---
Adam Chodorowski <ad...@ch...>

Emacs is a nice OS, but it lacks a good text editor. That's why I am using
Vim. 
    -- Anonymous

Re: [Docutils-develop] Forcing line breaks

[David G. <go...@us...>]

Adam Chodorowski wrote:
> Is there any way to force line breaks? Example of usage::
> 
>   :Name:    Adam Chodorowski
>   :Address: The Street
>             11111 The Town
>             The Country
>   :Phone:   +11-111111

If you're using a recent snapshot, it's already taken care of for you.
The "Address" field should produce the equivalent of a line_block
element, which is exactly what you describe.

I suspect that this is a document *fragment* you're showing us though.
In that case,

- You shouldn't really be using field lists in the first place.
  They're for extension syntax (docinfo & directive options).  I'll
  make this more explicit in the docs.  Perhaps a table or a
  definition list would be better?

- You could use the "line-block" directive:

      =======  =================
      Address  .. line-block::
                  The Street
                  11111 The Town
                  The Country
      =======  =================

> I looked through the documentation, but couldn't find any mention
> of it...

http://docutils.sf.net/spec/rst/directives.html#line-block

-- 
David Goodger  <go...@us...>  Open-source projects:
  - Python Docutils: http://docutils.sourceforge.net/
    (includes reStructuredText: http://docutils.sf.net/rst.html)
  - The Go Tools Project: http://gotools.sourceforge.net/

Re: [Docutils-develop] Forcing line breaks

[Adam C. <ad...@ch...>]

On Fri, 06 Sep 2002 20:11:44 -0400 David Goodger
<go...@us...> wrote:

> > Is there any way to force line breaks? Example of usage::
> > 
> >   :Name:    Adam Chodorowski
> >   :Address: The Street
> >             11111 The Town
> >             The Country
> >   :Phone:   +11-111111
> 
> If you're using a recent snapshot, it's already taken care of for you.
> The "Address" field should produce the equivalent of a line_block
> element, which is exactly what you describe.

I'm guessing that is only valid for a bibliographic fields...

> I suspect that this is a document *fragment* you're showing us though.

Exactly, although that snippet I gave you actually *is* part of a
bibliographic field list I would like the functionality in other places as
well.

> In that case,
> 
> - You shouldn't really be using field lists in the first place.
>   They're for extension syntax (docinfo & directive options).  I'll
>   make this more explicit in the docs.  Perhaps a table or a
>   definition list would be better?

I disagree strongly on this. Why on earth shouldn't fields lists be usable as
a construct of their own? Using a table to show contact information is ugly
and non-intuitive (if you only have contact information for one person; if you
have many it does makes sense), using a bulleted/numbered list is definately
not apropriate and a definition list doesn't really fit either.

Definition lists do fit *conceptually*, but unfortunately not with regard to
presentation. When you specify contact information or similar data, you almost
always do it like this::

  Name:    Adam Chodorowski
  Address: The Street 42
           11111 The City
  Country: Sweden
  Phone:   +46-8-1111111

Having definition lists is *not* intuitive for the reader, since it results in
(atleast for HTML)::

  Name:
     Adam Chodorowski

  Address:
     The Street 42
     11111 The City

  Country:
     Sweden

  Phone:
     +46-8-1111111

Not to mention that it takes more space, nobody excepts contact information to
be presented that way. Field lists are IMHO perfect for "single vertical table
rows". Just what the doctor ordered. ;-)

[...]
> > I looked through the documentation, but couldn't find any mention
> > of it...
> 
> http://docutils.sf.net/spec/rst/directives.html#line-block

That's exactly what I need, thanks. :-)

---
Adam Chodorowski <ad...@ch...>

If entropy is increasing, where is it coming from?

Re: [Docutils-develop] Forcing line breaks

[David G. <go...@us...>]

[Adam]
>>> Is there any way to force line breaks? Example of usage::
>>> 
>>>   :Name:    Adam Chodorowski
>>>   :Address: The Street
>>>             11111 The Town
>>>             The Country
>>>   :Phone:   +11-111111

[David]
>> If you're using a recent snapshot, it's already taken care of for
>> you. The "Address" field should produce the equivalent of a
>> line_block element, which is exactly what you describe.

[Adam]
> I'm guessing that is only valid for a bibliographic fields...

Yes.  Special processing in a specific context, which cannot be
assumed anywhere else.

>> - You shouldn't really be using field lists in the first place.
>>   They're for extension syntax (docinfo & directive options).  I'll
>>   make this more explicit in the docs.  Perhaps a table or a
>>   definition list would be better?
> 
> I disagree strongly on this. Why on earth shouldn't fields lists be
> usable as a construct of their own?

On April 25, I clarified the spec to say this about field lists: "They
are not intended to be an alternative to definition lists or tables."
I made this admonition stronger yesterday: "Field lists should only be
used when and where application code specifically expects them; they
should *not* be used as arbitrary constructs in documents."

Before you begin your reply, please read to the end.  (It's one of my
thinking-an-issue-through-to-the-end essays.)

> Definition lists do fit *conceptually*, but unfortunately not with
> regard to presentation. When you specify contact information or
> similar data, you almost always do it like this::
> 
>   Name:    Adam Chodorowski
>   Address: The Street 42
>            11111 The City
>   Country: Sweden
>   Phone:   +46-8-1111111

Actually, I would write it like this::

    Adam Chodorowski
    The Street 42
    11111 The City
    Sweden
    phone +46-8-1111111

Most of the labels are redundant; people know how to read addresses
from context.

> Having definition lists is *not* intuitive for the reader
...
> nobody excepts contact information to be presented that way.

I wouldn't expect contact information to be presented the "field list"
way either.  Are conventions so different in Sweden?  Do you really
need to label everything?  (But this is avoiding the real issue.)

> Field lists are IMHO perfect for "single vertical table rows". Just
> what the doctor ordered. ;-)

This may a case of abusing markup because it gives the desired
results.  In DocBook terms, it's like a doc writer using <emphasis>
instead of <glossterm>, because they want italics in the output.  A
*side effect* of <glossterm> may be italics, but the main effect may
be quite different (hyperlinking all glossterms to a glossary, for
example).

But I do see Adam's point.  I've been moving towards thinking about
field lists purely as an extension syntax, not as a generic construct.
 Partly this is due to outside influence, the incessant
"reStructuredText is too complex!" from certain parties.  So we have
to choose:

1. Field lists shall be restricted to extension syntax use (directive
   options, docinfo) only.

2. Field lists shall also be available to authors as a generic
   two-column table/list construct.

There are consequences.  If we choose #1, we should remove field list
support from writers; it would be an error for an unprocessed field
list to remain in the document tree.  If we choose #2, we should ask
ourselves, are field lists generic *enough*?

The current field list syntax (geared toward extension syntax use,
choice #1) was modeled after RFC 2822's fields and JavaDoc's "@tags".
It limits field names to single (possibly compound) words.  Anything
after whitespace is taken to be field arguments, which are
semantically and presentationally separate from field names.  Field
arguments allow the equivalent of a JavaDoc "@param name description"
tag.

In Adam's contact info block above, there's a "phone" field.  What if
he wants to differentiate between phone numbers (home, cell, pager)?
Let's assume that in Swedish we cannot rework the field names into
single words; we *have* to use multiple words.  We'd want this as
output::

    Home Phone:   +46-8-1111111
    Cell Phone:   +46-8-2222222
    Pager Number: +46-8-3333333

The closest we could get with current field lists would be like this::

    :Home-Phone:   +46-8-1111111
    :Cell-Phone:   +46-8-2222222
    :Pager-Number: +46-8-3333333

(Underscores could be used instead of hyphens.)  I doubt that this
would be acceptable to most document authors, and the output (with
hyphens intact) would look strange to readers.  The alternative is to
redefine field lists to allow multi-word field names, and use a
different syntax for field arguments.  Perhaps something like this::

    :Field name <field arguments>: Field body

Or perhaps we just drop the idea of field arguments altogether, and
rely on the application code to parse the field name as it likes.

Apart from the test suite, the only place where field arguments are
used is in the "meta" directive, which produces <meta> tags.  This is
from tools/test.txt::

    .. meta::
       :keywords: reStructuredText, test, parser
       :description lang=en: A test document, containing at least one
           example of each reStructuredText construct.

The "meta" directive code would have no problem extracting the
"lang=en" argument from the field name.  The "meta" directive would
specify that the first word of the field name would be taken as the
"name" attribute, and the rest should be "attname=value" attribute
definitions.

I'm beginning to like this change.  If we drop the notion of "field
arguments", field lists become simpler and fully generic.  Then I'd
drop my objection to their use as a generic document construct.  Any
objections to this change?

-- 
David Goodger  <go...@us...>  Open-source projects:
  - Python Docutils: http://docutils.sourceforge.net/
    (includes reStructuredText: http://docutils.sf.net/rst.html)
  - The Go Tools Project: http://gotools.sourceforge.net/

[Docutils-develop] Field arguments dropped (was Re: Forcing line breaks)

[David G. <go...@us...>]

I wrote:
> Or perhaps we just drop the idea of field arguments altogether, and
> rely on the application code to parse the field name as it likes.

And now it's implemented.  Field lists are now freely usable as generic
document constructs.  Field names may have multiple words, although
restrictions may be imposed by (and the interpretation depends on)
application code.  Short form: field lists are more general-purpose now,
with no problems anticipated.

-- 
David Goodger  <go...@us...>  Open-source projects:
  - Python Docutils: http://docutils.sourceforge.net/
    (includes reStructuredText: http://docutils.sf.net/rst.html)
  - The Go Tools Project: http://gotools.sourceforge.net/

Re: [Docutils-develop] Forcing line breaks

[Adam C. <ad...@ch...>]

On Sat, 07 Sep 2002 13:12:32 -0400 David Goodger
<go...@us...> wrote:

> > Definition lists do fit *conceptually*, but unfortunately not with
> > regard to presentation. When you specify contact information or
> > similar data, you almost always do it like this::
> > 
> >   Name:    Adam Chodorowski
> >   Address: The Street 42
> >            11111 The City
> >   Country: Sweden
> >   Phone:   +46-8-1111111
> 
> Actually, I would write it like this::
> 
>     Adam Chodorowski
>     The Street 42
>     11111 The City
>     Sweden
>     phone +46-8-1111111
> 
> Most of the labels are redundant; people know how to read addresses
> from context.

That's true, as long as you only have name and address I guess. But when you
start tacking on things like phone, mobile, email, ..., you have to prefix
them with something (atleast phone and mobile, I guess email would be clear
from the context :)).



> > Having definition lists is *not* intuitive for the reader
> ...
> > nobody excepts contact information to be presented that way.
> 
> I wouldn't expect contact information to be presented the "field list"
> way either.  Are conventions so different in Sweden?  Do you really
> need to label everything?  (But this is avoiding the real issue.)

Well, no, I guess we don't label addresses normally since everyone knows what
is what from the context. But when I also add phone number and such, I usually
put labels on everything (to be consistent).
 
[...]
> I'm beginning to like this change.  If we drop the notion of "field
> arguments", field lists become simpler and fully generic.  Then I'd
> drop my objection to their use as a generic document construct.  Any
> objections to this change?

No. :)

---
Adam Chodorowski <ad...@ch...>

Of course everyone knows that vim is the best text editor in the world.  
Anyone who tells you differently is either wrong, lying, or criminally 
insane.  (Or an emacs user, in which case they are wrong, lying and 
criminally insane).
    -- CmdrTaco / SlashDot