docutils-users Mailing List for Docutils: Documentation Utilities

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

> David Abrahams wrote:
>> So, being a CSS idiot, I don't know whether this means that I can
>> change it so that <h1 class="title"> is displayed differently from
>> <h1>.  Can I?
>
> Yes, you can.  tools/stylesheets/default.css shows how:
>
> h1.title {
>    text-align: center }
>
> h2.subtitle {
>    text-align: center }

Thank you again!
-- 
Dave Abrahams
Boost Consulting
www.boost-consulting.com

Michele Simionato wrote:
 > I want to insert a picture in a rst file, and produce both html and
 > latex. I have both a .gif and a .ps version of the figure.  The .gif
 > works in html but not in latex, the .ps works in latex but not in
 > html. Is there a custom way of solving the issue?

Not really, no.  There are some ideas on the to-do list though:
<http://docutils.sf.net/spec/notes.html#adaptable-file-extensions>
and <http://docutils.sf.net/spec/notes.html#conditional-directives>.

-- David Goodger

David Abrahams wrote:
> So, being a CSS idiot, I don't know whether this means that I can
> change it so that <h1 class="title"> is displayed differently from
> <h1>.  Can I?

Yes, you can.  tools/stylesheets/default.css shows how:

h1.title {
   text-align: center }

h2.subtitle {
   text-align: center }

-- David Goodger

Aahz <aa...@py...> writes:

> On Tue, Jul 29, 2003, Michael Hudson wrote:
>> David Abrahams <da...@bo...> writes:
>>> 
>>> I have a few ReST documents which need to use large, common sequences
>>> of text.  Is there any analogue to the 'C' preprocessor's #include
>>> directive for ReST?
>> 
>> .. include: /path/to/file
>
> I'm pretty sure that needs to be ``.. include::``; I've been bitten by
> forgetting the second colon several times.

Thanks, everyone; this is great!

-- 
Dave Abrahams
Boost Consulting
www.boost-consulting.com

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

> See <http://docutils.sourceforge.net/FAQ.html>, section 3.4.

So, being a CSS idiot, I don't know whether this means that I can
change it so that <h1 class="title"> is displayed differently from
<h1>.  Can I?

-- 
Dave Abrahams
Boost Consulting
www.boost-consulting.com

I want to insert a picture in a rst file, and produce both html and
latex. I have both a .gif and a .ps version of the figure.
The .gif works in html but not in latex, the .ps works
in latex but not in html. Is there a custom way of solving
the issue?

-- 
Michele Simionato - Dept. of Physics and Astronomy
210 Allen Hall Pittsburgh PA 15260 U.S.A.
Phone: 001-412-624-9041 Fax: 001-412-624-9163
Home-page: http://www.phyast.pitt.edu/~micheles/

On Tue, Jul 29, 2003, Michael Hudson wrote:
> David Abrahams <da...@bo...> writes:
>> 
>> I have a few ReST documents which need to use large, common sequences
>> of text.  Is there any analogue to the 'C' preprocessor's #include
>> directive for ReST?
> 
> .. include: /path/to/file

I'm pretty sure that needs to be ``.. include::``; I've been bitten by
forgetting the second colon several times.
-- 
Aahz (aa...@py...)           <*>         http://www.pythoncraft.com/

This is Python.  We don't care much about theory, except where it intersects 
with useful practice.  --Aahz

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

> David Abrahams wrote:
>  > I'm trying to put an image at the top of my page next to the main
>  > title.
> ..
>  > The only problem with this is that the <title>...</title> of the
>  > resulting HTML document contains "(logo)".  I'd like to eliminate
>  > that, but AFAICT there's no way to make a text-free substitution.
>  >
>  > Any ideas?
>
> Add an empty (no value) ":alt:" option to the "image" directive.
> Since images cannot be part of HTML <title> text, the image's
> alternate text is used.  Remove it and you're golden.  Note: empty
> ":alt:" options are a recent change; you may have to update your
> Docutils.

Awesome, it works!

-- 
Dave Abrahams
Boost Consulting
www.boost-consulting.com

David Abrahams wrote:
 > I'm trying to put an image at the top of my page next to the main
 > title.
...
 > The only problem with this is that the <title>...</title> of the
 > resulting HTML document contains "(logo)".  I'd like to eliminate
 > that, but AFAICT there's no way to make a text-free substitution.
 >
 > Any ideas?

Add an empty (no value) ":alt:" option to the "image" directive.
Since images cannot be part of HTML <title> text, the image's
alternate text is used.  Remove it and you're golden.  Note: empty
":alt:" options are a recent change; you may have to update your
Docutils.

-- David Goodger

David Abrahams <da...@bo...> writes:

> I have a few ReST documents which need to use large, common sequences
> of text.  Is there any analogue to the 'C' preprocessor's #include
> directive for ReST?

.. include: /path/to/file

I think.

Cheers,
mwh

-- 
  > Why are we talking about bricks and concrete in a lisp newsgroup?
  After long experiment it was found preferable to talking about why
  Lisp is slower than C++...
                        -- Duane Rettig & Tim Bradshaw, comp.lang.lisp

On Tue, Jul 29, 2003, David Abrahams wrote:
> 
> I have a few ReST documents which need to use large, common sequences
> of text.  Is there any analogue to the 'C' preprocessor's #include
> directive for ReST?

``.. include::``?
-- 
Aahz (aa...@py...)           <*>         http://www.pythoncraft.com/

This is Python.  We don't care much about theory, except where it intersects 
with useful practice.  --Aahz

See <http://docutils.sourceforge.net/FAQ.html>, section 3.4.

-- David Goodger

When I format the following:

------- schnipp -------
++++
 H1
++++

xx

====
 H2
====

xx

====
 Hx
====

xx
------- schnapp ------

With 

   python html.py --stylesheet=http://www.boost.org/boost.css -gdts ...

I get only one heading style, <h1>...</h1>.  I was expecting the
first section to be formatted <h1>...</h1> and the others to be
formatted <h2>...</h2>.  Are my expectations justified?

-- 
Dave Abrahams
Boost Consulting
www.boost-consulting.com

David Abrahams wrote:

> I have a few ReST documents which need to use large, common sequences
> of text.  Is there any analogue to the 'C' preprocessor's #include
> directive for ReST?

There's an ``include`` directive.

     .. include:: foo.txt

http://docutils.sourceforge.net/spec/rst/directives.html#including-an-external-document-fragment

-Ollie

-- 
Ollie Rutherfurd
http://www.rutherfurd.net/

I have a few ReST documents which need to use large, common sequences
of text.  Is there any analogue to the 'C' preprocessor's #include
directive for ReST?

TIA,
-- 
Dave Abrahams
Boost Consulting
www.boost-consulting.com

Warning: This is tweaky HTML formatting stuff

I'm trying to put an image at the top of my page next to the main
title.  The beginning of my ReST document looks like:


  +++++++++++++++++++++
   My Title |(logo)|__
  +++++++++++++++++++++

  .. |(logo)| image:: ../../../c++boost.gif

  __ ../../../index.htm


The only problem with this is that the <title>...</title> of the
resulting HTML document contains "(logo)".  I'd like to eliminate
that, but AFAICT there's no way to make a text-free substitution.

Any ideas?

TIA,
-- 
Dave Abrahams
Boost Consulting
www.boost-consulting.com

Brett g Porter wrote:
 > ...but then I want to be able to do
 >
 > ``SOME_USEFUL_STRUCT structData;``
 >    bla bla bla
 >
 > ...and have the text of SOME_USEFUL_STRUCT be a clickable link to
 > the documentation of that structure.
...
 > ...or maybe a role?:
 >
 > :parsed-literal:`SOME_USEFUL_STRUCT_ structData;`

Yes, a role would seem to be the solution.  Care to implement it?

 > I can't seem to mix parsed-literal blocks and definition lists.

Definition list terms can only be one line long, and they must be
simple text with no structural markup.  The second, indented line is
what triggers "definition list" recognition in the parser.  A
parsed-literal block, even if only one line, by definition contains
structural markup: the ".. parsed-literal::" text is not simple text,
but a directive.  And any indented second line would automatically be
subsumed into the directive's content.  So that approach is doomed in
multiple ways. ;-)

-- 
David Goodger    http://starship.python.net/~goodger
For hire: http://starship.python.net/~goodger/cv
Docutils: http://docutils.sourceforge.net/
(includes reStructuredText: http://docutils.sf.net/rst.html)

Bob Marshall wrote:
 >   Just a quickie; is it possible to specify styles for a
 > reStructuredText *table*? Specifically, I'd like to get rid of the
 > table gridlines (e.g. 'force' the HTML table attribute BORDER="0")?
...

 > For the record, my solution (hack) so far is thus:
 >
 > i) Specify a different style sheet

Always a good solution.  If this isn't enough, it could be an
indication that the HTML being produced by Docutils is inadequate and
could be improved.  That seems to be the case here.

 > ii) Hack the docutils\writers\html4css1.py file to change the values
 > passed to the self.starttag() method call's frame= and rules=
 > keyword arguments to 'void' and 'None' resp in the visit_table
 > method.

That may work for you, but Docutils can't use it.  Most people want
some kind of grid on their tables.  How to allow gridless tables via
stylesheets while defaulting to gridded tables?

 > the original frame="border" and rules="all" values seem to prevent
 > CSS from overrriding the table style w.r.t. borders

The problem is that CSS1 doesn't have styles equivalent to the "table"
element's attributes "frame" and "rules".  I experimented with
stylesheet settings of the "border" style, using Mac OS X Mozilla 1.4,
Safari 1.0 (khtml-based), and Internet Explorer 5.2.2.  There doesn't
seem to be any universal way to get nice-looking bordered tables using
CSS styles to add borders, but by *removing* the "frame" and "rules"
attributes altogether and adding a "border" attribute (valueless, as
described below), default (bordered) tables in all browsers look good.
Some research uncovered this:

     * The value "border" in the start tag of the TABLE element should
       be interpreted as the value of the frame attribute. It implies
       rules="all" and some default (non-zero) value for the border
       attribute.

     For example, the following definitions are equivalent:

     ...

     <TABLE border>
     <TABLE frame="border" rules="all">

     -- <http://www.w3.org/TR/html4/struct/tables.html#h-11.3.1>, near
        the bottom of section 11.3.1

I've made the change to html4css1.py's "HTMLTranslator.visit_table"
method.  I verified that Netscape 4.51 isn't adversely affected.
<http://docutils.sourceforge.net/tools/test.html#tables> has been
updated; please let me know if any browsers don't like the change.

This change allows borderless tables using these stylesheet entries::

     table.table {
       border: none }

     table.table td, table.table th {
       border: none }

(IOW, *removing* grids/borders using CSS works, but *adding* doesn't.)

-- 
David Goodger    http://starship.python.net/~goodger
For hire: http://starship.python.net/~goodger/cv
Docutils: http://docutils.sourceforge.net/
(includes reStructuredText: http://docutils.sf.net/rst.html)