From fredrik at pythonware.com  Thu Apr  6 10:02:30 2006
From: fredrik at pythonware.com (Fredrik Lundh)
Date: Thu, 6 Apr 2006 10:02:30 +0200
Subject: [Doc-SIG] introducing the experimental pytut wiki
References: <e0eoqc$c6k$1@sea.gmane.org>
Message-ID: <e12hup$5sr$1@sea.gmane.org>

> without further ado, here's
>
>     http://pytut.infogami.com/

for the record, the first week has seen been 172 edits by 8 con-
tributors, and 47 comments posted (by numerous contributors).
a considerable amount of edits are due to conversion issues, but
there's a lot of tweaking and tuning going on.

thanks to everyone who's contributed.

</F>




From fredrik at pythonware.com  Thu Apr  6 18:16:50 2006
From: fredrik at pythonware.com (Fredrik Lundh)
Date: Thu, 6 Apr 2006 18:16:50 +0200
Subject: [Doc-SIG] good style guides for python-style documentation ?
Message-ID: <e13eti$epd$1@sea.gmane.org>

over at the pytut wiki, "carndt" asked:

    Are there any guidelines about conventions concerning
    punctuation, text styles and language style (e.g. how
    to address the reader)?

any suggestions from this list ?

</F>




From gherman at darwin.in-berlin.de  Mon Apr 24 13:23:44 2006
From: gherman at darwin.in-berlin.de (Dinu Gherman)
Date: Mon, 24 Apr 2006 13:23:44 +0200
Subject: [Doc-SIG] Generating customized LaTeX?
Message-ID: <9e1a5937794fcc590ed387fc25fc37b1@darwin.in-berlin.de>

Hi,

I'm working on a project where I'd greatly benefit from generating
customized LaTeX from ReST, mainly for using existing LaTeX macros,
basically for stuff like itemized lists, tables, figures, and code
listings.

After briefly sniffing into docutils 0.4 I found a "newlatex2e"
writer, which makes me wonder if this would be a better start than
the older "latex2e" one? But the older one contains methods like
LaTeXTranslator.visit_admonition(...) which seem useful to me
(in this case for listings maybe). Maybe there is some short text
describing how to derive such a customized version of a docutils
writer?

And yes, I am aware of a simpler solution using the |...| syntax
combined with raw:: LaTeX without having to subclass or rewrite
a docutils writer, but the shortcoming with that is it doesn't
quite work well with multiple output formats (like HTML + LaTeX,
say).

Thanks,

Dinu


From Felix.Wiemann at gmx.net  Thu Apr 27 20:16:56 2006
From: Felix.Wiemann at gmx.net (Felix Wiemann)
Date: Thu, 27 Apr 2006 20:16:56 +0200
Subject: [Doc-SIG] Generating customized LaTeX?
References: <9e1a5937794fcc590ed387fc25fc37b1@darwin.in-berlin.de>
Message-ID: <87wtda289z.fsf@news2.ososo.de>

Dinu Gherman wrote:

> I'm working on a project where I'd greatly benefit from generating
> customized LaTeX from ReST, mainly for using existing LaTeX macros,
> basically for stuff like itemized lists, tables, figures, and code
> listings.
>
> After briefly sniffing into docutils 0.4 I found a "newlatex2e"
> writer, which makes me wonder if this would be a better start than
> the older "latex2e" one?

Yes and no.

The new LaTeX writer uses LaTeX macros for almost everything, so you
customize most things by adding code to the user stylesheet.  For
overriding emphasis handling, you'd create a user stylesheet that reads:

    \newcommand{\DNemphasis}[1]{\emph{#1}}

\DNemphasis means *D*ocutils *N*ode whose name is "emphasis".

\emph{#1} is the default definition, replace it with anything you like.

The downsides of the new LaTeX writer are that it's not documented at
all, and that it's not feature-complete yet (though it behaves better
than the old LaTeX writer in several edge cases).  I'd be willing to
provide support, though.

> But the older one contains methods like
> LaTeXTranslator.visit_admonition(...) which seem useful to me (in this
> case for listings maybe). Maybe there is some short text describing
> how to derive such a customized version of a docutils writer?

If you want to use Python code for customization (which in my experience
is more unwieldy than LaTeX code but provides much better support for
logic), I'd suggest you use the old LaTeX writer for now.

Look at writers/s5_html/__init__.py and tools/rst2s5.py for hints on how
to create a derived writer.  (The S5 writer is derived from the
html4css1 writer.)

HTH & HAND,
Felix

-- 
For private mail please ensure that the header contains 'Felix Wiemann'.

"the number of contributors [...] is strongly and inversely correlated with the
number of hoops each project makes a contributing user go through."      -- ESR


From fredrik at pythonware.com  Sun Apr 30 08:40:28 2006
From: fredrik at pythonware.com (Fredrik Lundh)
Date: Sun, 30 Apr 2006 08:40:28 +0200
Subject: [Doc-SIG] introducing the experimental pyref wiki
Message-ID: <e31m50$19b$1@sea.gmane.org>

(reposted from python-dev)

the pytut wiki (http://pytut.infogami.com/) has now been up and
running for one month, and has seen well over 250 edits from over
a dozen contributors.

to celebrate this, and to exercise the toolchain that I've deve-
loped for pytut and pyfaq (http://pyfaq.infogami.com/), I spent
a few hours putting together a hyperlinked mashup of the language
reference and portions of the library reference:

    http://pyref.infogami.com/

a couple of notes:

- all important "concepts" have unique URLs: this includes key-
  words, types, special methods and attributes, statements,
  builtin functions, and exceptions.

- the conversion and structure is a bit rough; especially the
  syntax/data model/execution model parts needs some serious
  refactoring. the "concept pages" are in a lot better shape.

- registered users can add comments to all pages (editing is
  currently "by invitation only"; mail me your infogami account
  if you want to help!)

- the documentation style used at the pyref site is tuned for
  authoring; an "end-user rendering" for python.org can look a
  lot different.  (all three sites can be made available in
  glorious XHTML for inclusion in arbitrary toolchains).

enjoy!

</F>