docutils-users

[Docutils-users] customize for literature book

[William D. <wi...@fl...>]

Hi,

I work for a book editor and we plan to put the book online.
It's not complex documentation books, but more literature.

We look first at docbook, but it's too much work to translate the
current text (xpress) and to customize the stylesheet.

We have also a newspaper to put online, so we'll need to make articles
ready for web quickly and easily. 

Do you think reStructuredText could help us ?

I develop in python so it's sure that i will use it for my own
documentation. But what about non-developer users ?

Am I in the good place ?

If yes, i've some questions about customization :
- where can i automatize the typography ? (like   before : ; ?...)
- how can i have a new type of paragraph (like a right-indented for
  citation between title and text) : i begin to look at adding a
  directive...
- how can i write special caracters (tm, (c)...) ?
- is interpreted text a way to customize ?

thanks for the answer and for the great works you did !

-- 
William Dode - http://flibuste.net

Re: [Docutils-users] customize for literature book

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

William Dode wrote:
> Am I in the good place ?

Yes, this is fine.  The docutils-develop list and Python's Doc-SIG list also
carry relevant discussions.

> Do you think reStructuredText could help us ?
>
> I develop in python so it's sure that i will use it for my own
> documentation. But what about non-developer users ?

Yes, reStructuredText could help you, but please realize that it's still
under development.  There are many rough edges and features that have yet to
be implemented (see <http://docutils.sf.net/spec/notes.html#to-do>).  As
long as the functionality you want is already implemented, non-developer use
is no problem.

If you're interested in sponsoring further development, I'm available.  See
my signature.

> If yes, i've some questions about customization :
> - where can i automatize the typography ? (like &nbsp; before : ; ?...)

What language are you publishing in?  In English we never put a space before
trailing punctuation.

In any case, unless convincing arguments appear, I don't think
reStructuredText will have any special character processing: no
"&nbsp;"-style character entities.  Docutils and reStructuredText use
Unicode internally and use Python's codec system for encoding and decoding
UTF-8, Latin-1, etc.  Simply insert a non-breaking space directly into your
source text, and tell Docutils what encoding you're using.

> - how can i write special caracters (tm, (c)...) ?

As above, insert the actual characters into your text.

In a recent Doc-SIG discussion, David Priest was asking to be able to use
XML character entities ("&nbsp;"-style).  I don't think that's appropriate
for reStructuredText, but he was unable to use UTF-8 encoded text files for
practical reasons, so he came up with an alternate scheme.  He will use a
"substitution table file" of this form::

    .. exclamation point:
    .. |excl| replace:: !

There are a couple of issues still to resolve.  See
<http://article.gmane.org/gmane.comp.python.documentation/418> for details.

> - how can i have a new type of paragraph (like a right-indented for
>   citation between title and text) : i begin to look at adding a
>   directive...

I can't say without seeing an example; can you provide one?  A directive may
be the correct option.

> - is interpreted text a way to customize ?

Yes, depending on what you want to do.  It's currently in development and
discussion.  Please provide examples if you want more specific answers.

> thanks for the answer and for the great works you did !

You're welcome.

-- David Goodger    http://starship.python.net/~goodger

Programmer/sysadmin for hire: http://starship.python.net/~goodger/cv

Re: [Docutils-users] customize for literature book

[William D. <wi...@fl...>]

David Goodger <go...@py...> writes:

> William Dode wrote:
> > Am I in the good place ?
> 
> Yes, this is fine.  The docutils-develop list and Python's Doc-SIG list also
> carry relevant discussions.

I just subscribe to docutils-develop (incredible 30 developers on this
project !!!).

> 
> > Do you think reStructuredText could help us ?
> >
> > I develop in python so it's sure that i will use it for my own
> > documentation. But what about non-developer users ?
> 
> Yes, reStructuredText could help you, but please realize that it's still
> under development.  There are many rough edges and features that have yet to
> be implemented (see <http://docutils.sf.net/spec/notes.html#to-do>).  As
> long as the functionality you want is already implemented, non-developer use
> is no problem.

What i've seen and try for now is near enough. And following the
development is a pleasure.

> 
> If you're interested in sponsoring further development, I'm available.  See
> my signature.

I think editors need tools like yours, but they begin to understand it very very
slowly... But be sure i'll mention you where i'll use your tools.

> 
> > If yes, i've some questions about customization :
> > - where can i automatize the typography ? (like &nbsp; before : ; ?...)
> 
> What language are you publishing in?  In English we never put a space before
> trailing punctuation.

In french. We need nbsp before : ; ? !. We need also special quotes << >>

> 
> In any case, unless convincing arguments appear, I don't think
> reStructuredText will have any special character processing: no
> "&nbsp;"-style character entities.  Docutils and reStructuredText use
> Unicode internally and use Python's codec system for encoding and decoding
> UTF-8, Latin-1, etc.  Simply insert a non-breaking space directly into your
> source text, and tell Docutils what encoding you're using.

I don't like to put it in the text when they can be put automaticaly.
I thought making a special html writers or use an external script
after the writers.

> 
> > - how can i write special caracters (tm, (c)...) ?
> 
> As above, insert the actual characters into your text.

It's not every time easy since we use html forms.

> 
> In a recent Doc-SIG discussion, David Priest was asking to be able to use
> XML character entities ("&nbsp;"-style).  I don't think that's appropriate
> for reStructuredText, but he was unable to use UTF-8 encoded text files for
> practical reasons, so he came up with an alternate scheme.  He will use a
> "substitution table file" of this form::
> 
>     .. exclamation point:
>     .. |excl| replace:: !

Good idea !

Just a litle question : how to don't have space with a replace ? (and
also with [#]) ?
Python |tm| work but Python|tm| will not work.

> 
> There are a couple of issues still to resolve.  See
> <http://article.gmane.org/gmane.comp.python.documentation/418> for details.
> 
> > - how can i have a new type of paragraph (like a right-indented for
> >   citation between title and text) : i begin to look at adding a
> >   directive...
> 
> I can't say without seeing an example; can you provide one?  A directive may
> be the correct option.

http://atheles.org/editeur.php?ref_editeur=&main=lyber&ref_lyber=273

there is a title, a subtitle (long line), a citation on the right (exergue).

if i could do .. exergue:: after i can manage it easily with stylesheet.

> 
> > - is interpreted text a way to customize ?
> 
> Yes, depending on what you want to do.  It's currently in development and
> discussion.  Please provide examples if you want more specific answers.

For example, if i want a special font or color for foreigns word in the middle of a
paragraph. Somethings like that :foreign:`bonjour`

bye

-- 
William Dode - http://flibuste.net

Re: [Docutils-users] customize for literature book

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

William Dode wrote:
> (incredible 30 developers on this project !!!).

Not so incredible.  Almost everybody who contributes becomes a developer.
Sometimes I offer, sometimes they ask.  The doors are wide open.

> I don't like to put it in the text when they can be put automaticaly.
> I thought making a special html writers or use an external script
> after the writers.

Looking at the article you cite, a specialized writer may be necessary.  It
seems that very publisher has a different article structure.  However, I'd
recommend a *pre*-processing script, *before* Docutils, to automate
insertion of non-breaking spaces and other character processing (like
turning "<<" into the &laquo; guillemet symbol).

> Just a litle question : how to don't have space with a replace ? (and
> also with [#]) ?
> Python |tm| work but Python|tm| will not work.

That's one of the "issues still to resolve":

>> There are a couple of issues still to resolve.  See
>> <http://article.gmane.org/gmane.comp.python.documentation/418> for details.

Specifically, I think the "\ " escape sequence idea works nicely.  So it
would be "Python\ |tm|".  It's ugly, but it works.  Or it will, once
implemented (soon).

>>> - how can i have a new type of paragraph (like a right-indented for
>>> citation between title and text) : i begin to look at adding a
>>> directive...
>> 
>> I can't say without seeing an example; can you provide one?  A directive may
>> be the correct option.
> 
> http://atheles.org/editeur.php?ref_editeur=&main=lyber&ref_lyber=273
> 
> there is a title, a subtitle (long line), a citation on the right (exergue).
> 
> if i could do .. exergue:: after i can manage it easily with stylesheet.

Interesting word, "exergue".  My French-English dictionary translates it to
"exergue" also in English, which means "the space beneath the device on a
coin or medal, which lists the date and/or place of minting".  My old "Micro
Robert En Poche" wasn't very helpful either, since my French is rusty.

The "exergue" appears to me to be a block quote used to introduce an article
(does it appear anywhere else?).  A directive could do it, or a
bibliographic field (":exergue: ..."), or just have your custom Writer (or a
transform) recognize the first block quote after the document title.
Another idea that was brought up recently was for a directive to add a
"class" attribute to arbitrary objects.  Something like this::

    =====
    Title
    =====

        .. class:: exergue

        This is the block quote "exergue"...

    Main text here...

Then you'd end up with <block_quote class="exergue">...</> and your
stylesheet can select on the class.  The "class" directive hasn't been
implemented yet.

>>> - is interpreted text a way to customize ?
>> 
>> Yes, depending on what you want to do.  It's currently in development and
>> discussion.  Please provide examples if you want more specific answers.
> 
> For example, if i want a special font or color for foreigns word in the middle
> of a paragraph. Somethings like that :foreign:`bonjour`

Yes, that's what interpreted text is for.

-- David Goodger    http://starship.python.net/~goodger

Programmer/sysadmin for hire: http://starship.python.net/~goodger/cv

Re: [Docutils-users] customize for literature book

[William D. <wi...@fl...>]

David Goodger <go...@py...> writes:

> William Dode wrote:
> > (incredible 30 developers on this project !!!).
> 
> Not so incredible.  Almost everybody who contributes becomes a developer.
> Sometimes I offer, sometimes they ask.  The doors are wide open.
> 
> > I don't like to put it in the text when they can be put automaticaly.
> > I thought making a special html writers or use an external script
> > after the writers.
> 
> Looking at the article you cite, a specialized writer may be necessary.  It
> seems that very publisher has a different article structure.  However, I'd
> recommend a *pre*-processing script, *before* Docutils, to automate
> insertion of non-breaking spaces and other character processing (like
> turning "<<" into the &laquo; guillemet symbol).
> 
> > Just a litle question : how to don't have space with a replace ? (and
> > also with [#]) ?
> > Python |tm| work but Python|tm| will not work.
> 
> That's one of the "issues still to resolve":

I use the cvs version, is there a lot of difference with the release ?

> 
> >> There are a couple of issues still to resolve.  See
> >> <http://article.gmane.org/gmane.comp.python.documentation/418> for details.
> 
> Specifically, I think the "\ " escape sequence idea works nicely.  So it
> would be "Python\ |tm|".  It's ugly, but it works.  Or it will, once
> implemented (soon).

Fine, it's not ugly, specialy when i can put it in a pre-processor !

> 
> >>> - how can i have a new type of paragraph (like a right-indented for
> >>> citation between title and text) : i begin to look at adding a
> >>> directive...
> >> 
> >> I can't say without seeing an example; can you provide one?  A directive may
> >> be the correct option.
> > 
> > http://atheles.org/editeur.php?ref_editeur=&main=lyber&ref_lyber=273
> > 
> > there is a title, a subtitle (long line), a citation on the right (exergue).
> > 
> > if i could do .. exergue:: after i can manage it easily with stylesheet.
> 
> Interesting word, "exergue".  My French-English dictionary translates it to
> "exergue" also in English, which means "the space beneath the device on a
> coin or medal, which lists the date and/or place of minting".  My old "Micro
> Robert En Poche" wasn't very helpful either, since my French is rusty.
> 
> The "exergue" appears to me to be a block quote used to introduce an article
> (does it appear anywhere else?).  A directive could do it, or a
> bibliographic field (":exergue: ..."), or just have your custom Writer (or a
> transform) recognize the first block quote after the document title.
> Another idea that was brought up recently was for a directive to add a
> "class" attribute to arbitrary objects.  Something like this::
> 
>     =====
>     Title
>     =====
> 
>         .. class:: exergue
> 
>         This is the block quote "exergue"...
> 
>     Main text here...
> 
> Then you'd end up with <block_quote class="exergue">...</> and your
> stylesheet can select on the class.  The "class" directive hasn't been
> implemented yet.

Ok, a customized directive for general purpose and this class directive
for exceptions. It's fine.

> 
> >>> - is interpreted text a way to customize ?
> >> 
> >> Yes, depending on what you want to do.  It's currently in development and
> >> discussion.  Please provide examples if you want more specific answers.
> > 
> > For example, if i want a special font or color for foreigns word in the middle
> > of a paragraph. Somethings like that :foreign:`bonjour`
> 
> Yes, that's what interpreted text is for.

Ok, now it's time for me to dig into the source and try...

Thanks, 

-- 
William Dode - http://flibuste.net

Re: [Docutils-users] customize for literature book

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

William Dode wrote:
> I use the cvs version, is there a lot of difference with the release ?

Yes, the CVS code is much ahead of the last release.  We're overdue for a
new release.

-- David Goodger