docutils-users Mailing List for Docutils: Documentation Utilities (Page 322)

Anonymous CVS access is still down, but I've fixed the hourly update script
so that it no longer clobbers good snapshots with bad.  I will manually
update the snapshots as required until SF's anon CVS is back up.

-- David Goodger    go...@py...

[David Goodger]
> Done.  Take a look in <http://docutils.sourceforge.net/tmp/>.

Thank you *so* much!

Cheers,

// m

p.s. I assume the 2002 in the filename is a typo?  Looking in the contents,
it appears so.

-

Mark McEahern wrote:
>> Is sourceforge CVS access down?  How can I get the latest dev snapshot?
> 
> Yes, it appears anonymous CVS access to sf.net is down:
> 
>    http://sourceforge.net/docman/display_doc.php?docid=2352&group_id=1#cvs
> 
> Unfortunately, the latest dev snapshot is an empty file--I assume because
> some cron job creates it from anonymous CVS?

Yes.  It's a shell script that doesn't know when to stop.  Someday it ought
to be rewritten it in Python...

> Can someone with dev access to CVS put a copy of the latest dev snapshot
> here and make it so that's not wiped out by some automated process that
> reads via anonymous CVS (assuming my conjecture is true):

Done.  Take a look in <http://docutils.sourceforge.net/tmp/>.

-- 
David Goodger  <go...@py...>  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/

[Me]
> Is sourceforge CVS access down?  How can I get the latest dev snapshot?

Yes, it appears anonymous CVS access to sf.net is down:

  http://sourceforge.net/docman/display_doc.php?docid=2352&group_id=1#cvs

Unfortunately, the latest dev snapshot is an empty file--I assume because
some cron job creates it from anonymous CVS?

Can someone with dev access to CVS put a copy of the latest dev snapshot
here and make it so that's not wiped out by some automated process that
reads via anonymous CVS (assuming my conjecture is true):

  http://docutils.sourceforge.net/#the-sandbox

Please.  Pretty please.

The latest dev snapshot is a joy to use--I boneheadedly deleted the original
files and I need to install it in Python 2.1 on a different machine (Zope,
that's right).

Thanks,

// mark

-

Is sourceforge CVS access down?  How can I get the latest dev snapshot?

Thanks,

// mark
-

I have checked in a preliminary reimplementation of the interpreted
text system.  A newly-expanded description of the interpreted text
implementation is here:

    http://docutils.sf.net/spec/notes.html#interpreted-text

A description of the "roles" currently supported is here:

    http://docutils.sf.net/spec/rst/interpreted.html

This change will break 3rd-party and sandbox code, as new doctree
elements (node types) have been introduced, with more to come.  The
core HTML writer will be kept up to date.

The snapshot has all the latest code:

    http://docutils.sf.net/docutils-snapshot.tgz

-- 
David Goodger  <go...@py...>  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/

Bruce Smith wrote:
> ... during "cd tools; ./buildhtml.py ../" I get some include
> errors -- output is below.
...
> Here are the relevant parts of my shell session, showing the include
> errors (about include4.txt, include5.txt, and include6.txt), and a
> few things I did to look into them. I didn't try to debug this, but
> I'll be glad to supply more info, or to try to debug it if someone
> more central to the project can't reproduce it.

Just pointing out the bug is useful, and your bug report was very
complete.  I had no problem reproducing the bug and it wasn't
difficult to locate or fix it.  It was an off-by-one error on a path
manipulation; fixed now.

> the check for the version of docutils I'm running doesn't work:
> 
> [!120] docutils/tools % ./quicktest.py --version
> Traceback (most recent call last):
...
> AttributeError: 'module' object has no attribute '__version'

Typo in the code, fixed now.

> BTW, Thanks loads for docutils!

You're welcome, and thanks for the bug report!

-- 
David Goodger  <go...@py...>  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/

Hi,

I've just downloaded docutils from the snapshot at

  http://docutils.sf.net/docutils-snapshot.tgz
  
and installed it into the python 2.2 that ships with Mac OS X 10.2.3,
i.e. /usr/bin/python, following the instructions on

  http://docutils.sourceforge.net/README.html

I noticed no problems during the install, and the test suite passes with no
errors, but during "cd tools; ./buildhtml.py ../" I get some include
errors -- output is below. (These occur before the test.txt file with its
intentional errors is mentioned in the output.)

There is also an error in the "./quicktest.py --version" command.

(I took a look at some of the generated HTML and it looks correct to my
untrained eye. See end of file for more pedantic details.)

BTW, Thanks loads for docutils! It looks like it'll help a lot with some
documentation I'm writing right now. (Not about anything related to Python,
unfortunately.)

Here are the relevant parts of my shell session, showing the include errors
(about include4.txt, include5.txt, and include6.txt), and a few things I did
to look into them. I didn't try to debug this, but I'll be glad to supply
more info, or to try to debug it if someone more central to the project
can't reproduce it.


[!100] docutils/test % ./alltests.py
.......................................... [rest of the 624 dots not shown]
----------------------------------------------------------------------
Ran 624 tests in 40.839s

OK
Elapsed time: 46.802 seconds
[!101] docutils/test % cd ../tools

[!105] docutils/tools % ./buildhtml.py ../
/// Processing directory: ../
    ::: Processing .txt: COPYING.txt
    ::: Processing .txt: FAQ.txt
    ::: Processing .txt: HISTORY.txt
    ::: Processing .txt: README.txt
/// Processing directory: ../build
/// Processing directory: ../build/lib
/// Processing directory: ../build/lib/docutils
/// Processing directory: ../build/lib/docutils/languages
/// Processing directory: ../build/lib/docutils/parsers
/// Processing directory: ../build/lib/docutils/parsers/rst
/// Processing directory: ../build/lib/docutils/parsers/rst/directives
/// Processing directory: ../build/lib/docutils/parsers/rst/languages
/// Processing directory: ../build/lib/docutils/readers
/// Processing directory: ../build/lib/docutils/readers/python
/// Processing directory: ../build/lib/docutils/transforms
/// Processing directory: ../build/lib/docutils/writers
/// Processing directory: ../docs
    ::: Processing .txt: tools.txt
/// Processing directory: ../docs/rst
    ::: Processing .txt: quickstart.txt
/// Processing directory: ../docs/rst/images
/// Processing directory: ../docutils
/// Processing directory: ../docutils/languages
/// Processing directory: ../docutils/parsers
/// Processing directory: ../docutils/parsers/rst
/// Processing directory: ../docutils/parsers/rst/directives
/// Processing directory: ../docutils/parsers/rst/languages
/// Processing directory: ../docutils/readers
/// Processing directory: ../docutils/readers/python
/// Processing directory: ../docutils/transforms
/// Processing directory: ../docutils/writers
/// Processing directory: ../spec
    ::: Processing .txt: doctree.txt
    ::: Processing .txt: notes.txt
    ::: Processing .txt: pysource.txt
    ::: Processing .txt: semantics.txt
    ::: Processing .txt: transforms.txt
    ::: Processing PEPs:
pep-0256.txt (text/x-rst) -> pep-0256.html
pep-0257.txt (text/x-rst) -> pep-0257.html
pep-0258.txt (text/x-rst) -> pep-0258.html
pep-0287.txt (text/x-rst) -> pep-0287.html
/// Processing directory: ../spec/howto
    ::: Processing .txt: i18n.txt
    ::: Processing .txt: rst-directives.txt
/// Processing directory: ../spec/rst
    ::: Processing .txt: alternatives.txt
    ::: Processing .txt: directives.txt
    ::: Processing .txt: introduction.txt
    ::: Processing .txt: problems.txt
    ::: Processing .txt: reStructuredText.txt
/// Processing directory: ../test
/// Processing directory: ../test/test_parsers
/// Processing directory: ../test/test_parsers/test_rst
/// Processing directory: ../test/test_parsers/test_rst/test_directives
    ::: Processing .txt: include1.txt
    ::: Processing .txt: include2.txt
    ::: Processing .txt: include3.txt
../test/test_parsers/test_rst/test_directives/include3.txt:3: (SEVERE/4) Problems with "include" directive path:
[Errno 2] No such file or directory: 'test/test_parsers/test_rst/test_directives/includes/include4.txt'.

.. include:: includes/include4.txt
SystemMessage: ../test/test_parsers/test_rst/test_directives/include3.txt:3: (SEVERE/4) Problems with "include" directive path:
[Errno 2] No such file or directory: 'test/test_parsers/test_rst/test_directives/includes/include4.txt'.

.. include:: includes/include4.txt
input line 3
module /usr/lib/python2.2/site-packages/docutils/utils.py, line 172, function system_message
        Error (SystemMessage): ../test/test_parsers/test_rst/test_directives/include3.txt:3: (SEVERE/4) Problems with "include" directive path:
[Errno 2] No such file or directory: 'test/test_parsers/test_rst/test_directives/includes/include4.txt'.

.. include:: includes/include4.txt
    ::: Processing .txt: raw1.txt
/// Processing directory: ../test/test_parsers/test_rst/test_directives/includes
    ::: Processing .txt: include4.txt
../test/test_parsers/test_rst/test_directives/includes/include4.txt:3: (SEVERE/4) Problems with "include" directive path:
[Errno 2] No such file or directory: 'test/test_parsers/test_rst/test_directives/includes/include5.txt'.

.. include:: include5.txt
SystemMessage: ../test/test_parsers/test_rst/test_directives/includes/include4.txt:3: (SEVERE/4) Problems with "include" directive path:
[Errno 2] No such file or directory: 'test/test_parsers/test_rst/test_directives/includes/include5.txt'.

.. include:: include5.txt
input line 3
module /usr/lib/python2.2/site-packages/docutils/utils.py, line 172, function system_message
        Error (SystemMessage): ../test/test_parsers/test_rst/test_directives/includes/include4.txt:3: (SEVERE/4) Problems with "include" directive path:
[Errno 2] No such file or directory: 'test/test_parsers/test_rst/test_directives/includes/include5.txt'.

.. include:: include5.txt
    ::: Processing .txt: include5.txt
../test/test_parsers/test_rst/test_directives/includes/include5.txt:3: (SEVERE/4) Problems with "include" directive path:
[Errno 2] No such file or directory: 'test/test_parsers/test_rst/test_directives/includes/more/include6.txt'.

.. include:: more/include6.txt
SystemMessage: ../test/test_parsers/test_rst/test_directives/includes/include5.txt:3: (SEVERE/4) Problems with "include" directive path:
[Errno 2] No such file or directory: 'test/test_parsers/test_rst/test_directives/includes/more/include6.txt'.

.. include:: more/include6.txt
input line 3
module /usr/lib/python2.2/site-packages/docutils/utils.py, line 172, function system_message
        Error (SystemMessage): ../test/test_parsers/test_rst/test_directives/includes/include5.txt:3: (SEVERE/4) Problems with "include" directive path:
[Errno 2] No such file or directory: 'test/test_parsers/test_rst/test_directives/includes/more/include6.txt'.

.. include:: more/include6.txt
/// Processing directory: ../test/test_parsers/test_rst/test_directives/includes/more
    ::: Processing .txt: include6.txt
/// Processing directory: ../test/test_readers
/// Processing directory: ../test/test_readers/test_pep
/// Processing directory: ../test/test_readers/test_python
/// Processing directory: ../test/test_transforms
/// Processing directory: ../tools
    ::: Processing .txt: test.txt
../tools/test.txt:87: (ERROR/3) Undefined substitution referenced: "problematic".
../tools/test.txt:293: (ERROR/3) Unknown target name: "5".
../tools/test.txt:302: (ERROR/3) Unknown target name: "nonexistent".
../tools/test.txt:327: (ERROR/3) Unknown target name: "hyperlink reference without a target".
../tools/test.txt:340: (ERROR/3) Unknown target name: "duplicate target names".
/// Processing directory: ../tools/stylesheets
[!106] docutils/tools % 

the files reported as missing do appear to be there, however:

[!107] docutils/tools % cd ..
[!108] python/docutils % l test/test_parsers/test_rst/test_directives/includes
total 16
0 ./              0 ../             8 include4.txt    8 include5.txt    0 more/
[!109] python/docutils % 

the check for the version of docutils I'm running doesn't work:

[!119] python/docutils % cd tools
[!120] docutils/tools % ./quicktest.py --version
Traceback (most recent call last):
  File "./quicktest.py", line 211, in ?
    main()
  File "./quicktest.py", line 195, in main
    inputFile, outputFile, outputFormat, optargs = getArgs()
  File "./quicktest.py", line 127, in getArgs
    return posixGetArgs(sys.argv[1:])
  File "./quicktest.py", line 146, in posixGetArgs
    print >>sys.stderr, ('quicktest.py (Docutils %s)'
AttributeError: 'module' object has no attribute '__version'
Exit 1

Pedantic details:

% ls -l docutils-snapshot.gz
-rw-r--r--  1 bruce  admin  407326 Jan  8 19:31 docutils-snapshot.gz

(timezone is PST; modtime is probably the time of downloading)

(The file extension was apparently renamed from .tgz to .gz by Apple's new
browser Safari when it downloaded the file.)

% md5 docutils-snapshot.gz
MD5 (docutils-snapshot.gz) = fd48f2fe3f0ffee04e00ea16cd4846a2

I was worried about long pathnames in the tarball being mangled by Stuffit
Expander, which (so I've read) uses Apple's tar rather than gnutar, but I
would have expected much worse errors if that had happened, and the include
files reported missing are present according to my shell, as shown above.

Just to make sure, I manually unpacked the archive with both tar and gnutar
and got the same-sized results according to du and the exact same results
according to diff -r, and diff -r of that docutils directory with
the one produced by Stuffit Expander (and from which I installed, ran tests,
and ran buildhtml) showed only the kind of extra files I'd expect (.html,
.pyc, alltests.out).

My system has several other pythons installed, but none of them are called
'python' on my shell path, so I don't think they can interfere.

- Bruce Smith

Brett g Porter wrote:
> It's probably staring me in the face, but what's the correct reST
> way to get characters like HTML character entities?

Just type the characters into your input file, using whatever extended
character set input mechanism your OS has.  Save the file using
whatever encoding you want (Latin-1, UTF-8, cp1252, unicode-escape,
etc.), and tell the Docutils tool what that encoding is
(-i/--input-encoding option).

The default output encoding, UTF-8, is well-supported and handles all
Unicode characters.

> I can't be the first to want to include "©" or "™" in a
> document.

Unfortunately, there's no 'html-character-entity' codec in the stdlib
[#]_.  If you were to use such a codec though, you'd have to encode
every "&" as "&" (unless it was a forgiving codec).  Does such a
codec exist?

.. [#] There is an "xmlcharrefreplace" error handler in Python 2.3,
   but it only converts characters to "©" forms, not "©",
   and only when encoding.  I don't know of an official codec for
   *decoding* character entities.

> I know that HTML isn't the only output format supported, so I'm not
> surprised that character entities aren't just passed through, I
> guess.

:)

-- 
David Goodger  <go...@py...>  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/

It's probably staring me in the face, but what's the correct reST way to get
characters like HTML character entities? I can't be the first to want to
include "©" or "™" in a document. I know that HTML isn't the only
output format supported, so I'm not surprised that character entities aren't
just passed through, I guess.

[David Goodger]
> Fred Drake pointed out that Python 2.1 didn't have the "compiler"
> package as part of the standard library (it was a separate
> install), and that's crucial to the Python Source Reader work
> that's ongoing.  Therefore I've decided to upgrade the minimum
> Python requirement to 2.2 (2.2.2 recommended).  Everything except
> the test suite and the docutils/readers/python code still works
> with Python 2.1 though.

Thanks Fred, Tony, and Benja, for your input.  I agree that Jython
currently at 2.1 presents a strong case for maintaining 2.1
compatibility.  The compiler package was in the Tools/ directory of
the Python source distribution, complete with a Distutils setup.py for
installation.

I wonder, does the compiler package work with Jython at all?  Benja?

Another issue is that I've been using tokenize.py's generate_tokens()
call in docutils/readers/python/moduleparser.py, which uses
generators, which requires Python 2.2.  Although this has been more of
an experiment than a requirement, it was a pleasant experiment and it
would be painful and a waste to reimplement it without iterators and
generators.

I put back the pre-generators difflib.py (used by the test suite) and
added footnotes to the README and the home page saying:

   Python 2.1 may be used providing the compiler package is
   installed.  The compiler package can be found in the Tools/
   directory of Python's source distribution.

[Fred L. Drake, Jr.]
> I've not dug into the alltests.py script yet; perhaps there's a way
> to do something similar to the "skipped tests" idea that we use with
> the Python test suite.  That's probably more a matter of mechanics
> than anything.  I won't have time to look into that for at least a
> few days; if anyone beats me to it I won't complain.  ;-)

Done.  The tests pass but report "test skipped" to stderr, under
Python 2.1.

-- 
David Goodger  <go...@py...>  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/

Benja Fallenstein writes:
 > My project [http://gzz.info] is using ReST heavily for documentation (we 
 > intend to write all future documentation in it, and have converted some 
 > of the existing). However, since we're a Java project, we use it through 
 > Jython, whose newest version is currently up to par with Python 2.1. 

Jython is a really good reason to maintain Python 2.1 compatibility in
my book.


  -Fred

-- 
Fred L. Drake, Jr.  <fdrake at acm.org>
PythonLabs at Zope Corporation

Hi David,

David Goodger wrote:
> I have fixed the remaining (known) bugs related to Python 2.3 and PyXML.
> 
> Fred Drake pointed out that Python 2.1 didn't have the "compiler" package as
> part of the standard library (it was a separate install), and that's crucial
> to the Python Source Reader work that's ongoing.  Therefore I've decided to
> upgrade the minimum Python requirement to 2.2 (2.2.2 recommended).
> Everything except the test suite and the docutils/readers/python code still
> works with Python 2.1 though.

My project [http://gzz.info] is using ReST heavily for documentation (we 
intend to write all future documentation in it, and have converted some 
of the existing). However, since we're a Java project, we use it through 
Jython, whose newest version is currently up to par with Python 2.1. 
Therefore, I'd be much happier if you could formally keep the docutils 
requirement at 2.1 for everything except the Python reader (or say, 
"Requirement: Python 2.2 or Python 2.1 with the compiler package 
installed"). When a 2.2-compliant Jython ever comes out, this won't be 
an issue any more.

Thanks,
- Benja

David Goodger wrote:
> ...that Python 2.1 didn't have the "compiler" package as
> part of the standard library (it was a separate install), and
> that's crucial to the Python Source Reader work that's ongoing.
> Therefore I've decided to upgrade the minimum Python requirement
> to 2.2 (2.2.2 recommended).

I don't have any personal (!) objection to specifying 2.2, but it's
surely easy enough to require the compiler package, and provide a
reference copy on the docutils site for those who install without the
appropriate bit of source/Tools/whatever.

Whether there was significant *change* in the compiler code in the
interim, though, which might also be influential, I can't remember.

Of course, this might just be that "one thing" that's enough to tip your
decision on which version of Python to go for.

Tibs

--
Tony J Ibbs (Tibs)      http://www.tibsnjoan.co.uk/
Give a pedant an inch and they'll take 25.4mm
(once they've established you're talking a post-1959 inch, of course)
My views! Mine! Mine! (Unless Laser-Scan ask nicely to borrow them.)

David Goodger writes:
 > I have fixed the remaining (known) bugs related to Python 2.3 and PyXML.

Yee haw!  ;-)

 > Fred Drake pointed out that Python 2.1 didn't have the "compiler" package as
 > part of the standard library (it was a separate install), and that's crucial
 > to the Python Source Reader work that's ongoing.  Therefore I've decided to
 > upgrade the minimum Python requirement to 2.2 (2.2.2 recommended).

It's not clear that this is the right way to deal with this; I'd be
happy that just the one component isn't necessarily available with
Python 2.1.x unless the compiler package is installed.

(I vaguely recall that the compiler package shipped as part of the
source package, but not as part of the standard library, but I'm not
sure offhand.  Maybe it was in the Tools/ directory?)

I've not dug into the alltests.py script yet; perhaps there's a way to
do something similar to the "skipped tests" idea that we use with the
Python test suite.  That's probably more a matter of mechanics than
anything.  I won't have time to look into that for at least a few
days; if anyone beats me to it I won't complain.  ;-)

 > Everything except the test suite and the docutils/readers/python code still
 > works with Python 2.1 though.

Which means the tests need to run, at least for the parts that are
supposed to work!  ;-)


  -Fred

-- 
Fred L. Drake, Jr.  <fdrake at acm.org>
PythonLabs at Zope Corporation

I have fixed the remaining (known) bugs related to Python 2.3 and PyXML.

Fred Drake pointed out that Python 2.1 didn't have the "compiler" package as
part of the standard library (it was a separate install), and that's crucial
to the Python Source Reader work that's ongoing.  Therefore I've decided to
upgrade the minimum Python requirement to 2.2 (2.2.2 recommended).
Everything except the test suite and the docutils/readers/python code still
works with Python 2.1 though.

-- 
David Goodger  <go...@py...>  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/

I just checked in a change to docutils/frontend.py, removing some nasty
internals-fiddling code (in ``ConfigParser.get_section()``) and replacing it
with simpler, correct code (possibly a bit slower, but so what).  This was
prompted by bug reports from Fred Drake and Guido van Rossum (thank you!),
who ran Docutils with the newly-released Python 2.3a1, in which some
ConfigParser internals had changed.

There may be another bug that only shows up with Python 2.3, but I won't be
able to check it until Thursday or Friday.

Anybody using Python 2.3 should definitely get the latest Docutils code from
CVS or from the snapshot: <http://docutils.sf.net/docutils-snapshot.tgz>.

Happy New Year!

-- 
David Goodger  <go...@py...>  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/

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

> David Abrahams wrote:
>> I'm writing a document with ReST, and I need to insert the titles of
>> several books.  Technically, book titles are supposed to be
>> underlined.
>
> According to whom?  

Some outdated reference I found on the web <wink>.

> *The Chicago Manual of Style*, which I use as my typographical
> bible, says:
>
>     Titles and subtitles of published books, ... are set in italics
>     when they are mentioned in the text or notes.
>
>     (14th edition, section 7.133)

You're right.  I found a more up-to-date reference after I posted.
Sorry for the line noise.

> If you want to indicate "book title" separately from "emphasis",
> which is perfectly valid, that's a different question.  Has to do
> with interpreted text.  There's already a related to-do list entry:
>
>   Perhaps the default implicit role for interpreted text could be
>   "title", as in, "title of a book".  It'd be a text-only reference,
>   no hyperlink.  Idea from Aahz' 2002-05-09 Doc-SIG post.

Eventually, there will be equivalents of every possible XML tag, won't
there <0.5 wink>?

-- 
                       David Abrahams
   da...@bo... * http://www.boost-consulting.com
Boost support, enhancements, training, and commercial distribution

David Ascher wrote:
> Pedantically yours,

Pedantic perhaps, but at least consistent:
<http://docutils.sf.net/spec/rst/problems.html#underlining>

-- David Goodger    go...@py...

PS: it's difficult to keep track of a thread where everyone is named
David...  ;-)
-- 
Aahz (aa...@py...)           <*>         http://www.pythoncraft.com/

"There are three kinds of lies: Lies, Damn Lies, and Statistics."  --Disraeli

On Mon, Dec 30, 2002, David Abrahams wrote:
> 
> I'm writing a document with ReST, and I need to insert the titles of
> several books.  Technically, book titles are supposed to be
> underlined.  What's the appropriate ReST representation?

I've been using ``*``, which on my system is emitted as italics.
-- 
Aahz (aa...@py...)           <*>         http://www.pythoncraft.com/

"There are three kinds of lies: Lies, Damn Lies, and Statistics."  --Disraeli

David Goodger wrote:
> David Abrahams wrote:
> 
>>I'm writing a document with ReST, and I need to insert the titles of
>>several books.  Technically, book titles are supposed to be
>>underlined.
> 
> 
> According to whom?  *The Chicago Manual of Style*, which I use as my
> typographical bible, says:
> 
>     Titles and subtitles of published books, ... are set in italics
>     when they are mentioned in the text or notes.
> 
>     (14th edition, section 7.133)

This matches the information I got from typesetting books (back in a previous 
life when I used to deal such things =).

--david

David Abrahams wrote:
> I'm writing a document with ReST, and I need to insert the titles of
> several books.  Technically, book titles are supposed to be
> underlined.

According to whom?  *The Chicago Manual of Style*, which I use as my
typographical bible, says:

    Titles and subtitles of published books, ... are set in italics
    when they are mentioned in the text or notes.

    (14th edition, section 7.133)

I looked up every reference to underlines, and they are exclusively used to
indicate italics to the typesetter (early typewriters typically didn't have
italic functionality ;).

If you want to indicate "book title" separately from "emphasis", which is
perfectly valid, that's a different question.  Has to do with interpreted
text.  There's already a related to-do list entry:

  Perhaps the default implicit role for interpreted text could be
  "title", as in, "title of a book".  It'd be a text-only reference,
  no hyperlink.  Idea from Aahz' 2002-05-09 Doc-SIG post.

> What's the appropriate ReST representation?

Ain't none, sorry.  For a rationale, see
<http://docutils.sf.net/spec/rst/problems.html#underlining>.

-- 
David Goodger  <go...@py...>  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/

David Abrahams wrote:
> Hi,
> 
> I'm writing a document with ReST, and I need to insert the titles of
> several books.  Technically, book titles are supposed to be
> underlined.  What's the appropriate ReST representation?

Technically, underlines are instructions from the author of a manuscript to 
the typesetter to use emphasis.  No "real" publisher ever uses underlines 
except for advertising/marketing copy purposes.

Pedantically yours,

--david

Hi,

I'm writing a document with ReST, and I need to insert the titles of
several books.  Technically, book titles are supposed to be
underlined.  What's the appropriate ReST representation?

TIA,
-- 
                       David Abrahams
   da...@bo... * http://www.boost-consulting.com
Boost support, enhancements, training, and commercial distribution