docutils-users — General discussions, questions, help requests.

Re: [Docutils-users] rst2odt and odf-config-file option

[Guenter M. <mi...@us...>]

On 2019-02-08, Dave Kuhlman wrote:

...

> So, I need to ask: We want a *single* version that runs under both
> Python 2 and Python 3, right?

This is a long term goal, but currently, Docutils requires conversion with
2to3 during installation to run with Py 3.

> Since a version that has been converted with `2to3` only runs under
> Python 3, I'll need to do the following:

> 1. Convert `odf_odt/__init__.py` so that it runs under both Python 2
>    and Python 3.  Then do a commit and check-in.

> 2. Add Gilles's change.  Then do a commit and check-in.

> 3. Do the clean-up for `flake8` and `pep8`.  Then do a commit and
>    check-in.

> I'm pretty sure that is what we want.  But, I thought I'd ask,
> because the number of changes needed for Python 3 is quite large.

This will become easier once we drop supporting Python 2.6 and older 3.x
versions after the 0.15 release.

> In the meantime, I'll get started.  Suggestions and guidance will be
> welcomed.

If you are not put off by the large changes, go ahead now. Otherwise add the
change to the Python-2 version and run the tests on both.

I do the Python 3 tests with

  # convert with 2to3:
  
  cd ~/Code/Python/docutils/docutils
  python3 setup.py build || exit $?
  
  # and run the tests there::
  
  python3.5 test3/alltests.py || exit $?


Günter

Re: [Docutils-users] rst2odt and odf-config-file option

[Dave K. <dku...@da...>]

I've run into a bit of a problem.

I've used docutils `odf_odt/__init__.py` under Python3.  That works.
But, the reason is because the version I've used is out of the
Anaconda Python 3 distribution, *and* that has been converted for
Python 3.  The version in the docutils SVN repository has *not* been
converted.  Maybe Gilles is using the Anaconda version, too.  I'm
pretty sure that they (the people at `https://www.anaconda.com`) ran
`odf_odt/__init__.py` through `2to3` and used that result, as is.
When I run the Python 2 version through `2to3` I get a file that's
identical to theirs, except for one more recent change.

So, I need to ask: We want a *single* version that runs under both
Python 2 and Python 3, right?

Since a version that has been converted with `2to3` only runs under
Python 3, I'll need to do the following:

1. Convert `odf_odt/__init__.py` so that it runs under both Python 2
   and Python 3.  Then do a commit and check-in.

2. Add Gilles's change.  Then do a commit and check-in.

3. Do the clean-up for `flake8` and `pep8`.  Then do a commit and
   check-in.

I'm pretty sure that is what we want.  But, I thought I'd ask,
because the number of changes needed for Python 3 is quite large.

In the meantime, I'll get started.  Suggestions and guidance will be
welcomed.

Dave


On Thu, Feb 07, 2019 at 12:04:47PM -0800, Dave Kuhlman wrote:
> Gilles,
> 
> Ugh.  Did I really do that?
> 
> Thanks for this fix.
> 
> I'll do some testing and will check the unit tests.  Then I'll push
> it back to the repo.
> 
> Question for the docutils list: When I apply the `flake8` style and
> error checker to `__init__.py`, I get lots of warnings (405 when I
> count them with `wc`).  Most of them have to do with indentation,
> missing or extra blank lines, missing or extra spaces, etc.  I'm
> willing to clean those up.  Or, would that amount of changes be too
> disruptive (for example, in making svn history less useful)?  Anyone
> have an opinion?  Clean it up?  Leave it alone?  If I do it, I'll
> make an extra check-in with only those cleanup changes.
> 
> Dave K
> 
> On Thu, Feb 07, 2019 at 01:48:42PM +0100, POIRET via Docutils-users wrote:
> >    Hello,
> > 
> >    I guess I've found a bug on rst2odt.py
> > 
> >    --
> > 
> >    I wanted to apply custom style with rst2odt, and discovered the
> >    --odf-config-file option.
> > 
> >    This option allows to map the default style to a custom one (so, used in
> >    conjunction with --template option).
> > 
> >    But it was not working on my environment (Debian 9, python3, docutils 1.4)
> > 
> >    --
> > 
> >    The __init__ method (l. 888) of the ODFTranslator class initializes a
> >    dictionary : format_map, but it's filled only for python2
> > 
> >    Involved file:
> >    /usr/lib/python3/dist-packages/docutils/writers/odf_odt/__init__.py
> > 
> >           parser = ConfigParser()
> >                parser.read(self.settings.odf_config_file)
> >                for rststyle, format in parser.items("Formats"):
> >                    if rststyle not in self.used_styles:
> >                        self.document.reporter.warning(
> >                            'Style "%s" is not a style used by odtwriter.' % (
> >                                rststyle, ))
> >                    if sys.version_info.major == 2:
> >                        self.format_map[rststyle] = format.decode('utf-8')
> >                   # my addition below
> > 
> >                   else:
> >                        self.format_map[rststyle] = format
> > 
> >    ---
> > 
> >  After applying my update, it works. (never tested with python2)
> > 
> > 
> >    Let me know if I can do something else.
> > 
> >    Regards,
> > 
> >    --
> > 
> >    Gilles
> > 
> >     
> > 
> >     
> > 
> >     
> 
> 
> > _______________________________________________
> > Docutils-users mailing list
> > Doc...@li...
> > https://lists.sourceforge.net/lists/listinfo/docutils-users
> > 
> > Please use "Reply All" to reply to the list.
> 
> 
> -- 
> 
> Dave Kuhlman
> http://www.davekuhlman.org
> 
> 
> _______________________________________________
> Docutils-users mailing list
> Doc...@li...
> https://lists.sourceforge.net/lists/listinfo/docutils-users
> 
> Please use "Reply All" to reply to the list.

-- 

Dave Kuhlman
http://www.davekuhlman.org

Re: [Docutils-users] rst2odt and odf-config-file option

[Matěj C. <mc...@ce...>]

On 2019-02-07, 20:04 GMT, Dave Kuhlman wrote:
> Question for the docutils list: When I apply the `flake8` 
> style and error checker to `__init__.py`, I get lots of 
> warnings (405 when I count them with `wc`).  Most of them have 
> to do with indentation, missing or extra blank lines, missing 
> or extra spaces, etc.  I'm willing to clean those up.  Or, 
> would that amount of changes be too disruptive (for example, 
> in making svn history less useful)?  Anyone have an opinion?  
> Clean it up?  Leave it alone?  If I do it, I'll make an extra 
> check-in with only those cleanup changes.

I have no authority to speak for anybody, but my comment would 
be:

+1 but do it in one commit named "PEP8ization" or something like 
that, which should in effect have no change to the 
functionality. Don't mix it with the real changes like fixing 
bugs.

Matěj
-- 
https://matej.ceplovi.cz/blog/, Jabber: mc...@ce...
GPG Finger: 3C76 A027 CA45 AD70 98B5  BC1D 7920 5802 880B C9D8
 
Give a man a regular expression and he’ll match a string… teach
him to make his own regular expressions and you’ve got a man with
problems.
  -- yakugo in http://regex.info/blog/2006-09-15/247#comment-3022

Re: [Docutils-users] rst2odt and odf-config-file option

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

Flake8: As long as you do a separate check-in, I don't see a problem.
+0, because "A Foolish Consistency is the Hobgoblin of Little Minds"
(as noted in PEP 8 itself).

David Goodger
<https://david.goodger.org>

On Thu, 7 Feb 2019 at 14:32, Dave Kuhlman <dku...@da...> wrote:
>
> Gilles,
>
> Ugh.  Did I really do that?
>
> Thanks for this fix.
>
> I'll do some testing and will check the unit tests.  Then I'll push
> it back to the repo.
>
> Question for the docutils list: When I apply the `flake8` style and
> error checker to `__init__.py`, I get lots of warnings (405 when I
> count them with `wc`).  Most of them have to do with indentation,
> missing or extra blank lines, missing or extra spaces, etc.  I'm
> willing to clean those up.  Or, would that amount of changes be too
> disruptive (for example, in making svn history less useful)?  Anyone
> have an opinion?  Clean it up?  Leave it alone?  If I do it, I'll
> make an extra check-in with only those cleanup changes.
>
> Dave K
>
> On Thu, Feb 07, 2019 at 01:48:42PM +0100, POIRET via Docutils-users wrote:
> >    Hello,
> >
> >    I guess I've found a bug on rst2odt.py
> >
> >    --
> >
> >    I wanted to apply custom style with rst2odt, and discovered the
> >    --odf-config-file option.
> >
> >    This option allows to map the default style to a custom one (so, used in
> >    conjunction with --template option).
> >
> >    But it was not working on my environment (Debian 9, python3, docutils 1.4)
> >
> >    --
> >
> >    The __init__ method (l. 888) of the ODFTranslator class initializes a
> >    dictionary : format_map, but it's filled only for python2
> >
> >    Involved file:
> >    /usr/lib/python3/dist-packages/docutils/writers/odf_odt/__init__.py
> >
> >           parser = ConfigParser()
> >                parser.read(self.settings.odf_config_file)
> >                for rststyle, format in parser.items("Formats"):
> >                    if rststyle not in self.used_styles:
> >                        self.document.reporter.warning(
> >                            'Style "%s" is not a style used by odtwriter.' % (
> >                                rststyle, ))
> >                    if sys.version_info.major == 2:
> >                        self.format_map[rststyle] = format.decode('utf-8')
> >                   # my addition below
> >
> >                   else:
> >                        self.format_map[rststyle] = format
> >
> >    ---
> >
> >  After applying my update, it works. (never tested with python2)
> >
> >
> >    Let me know if I can do something else.
> >
> >    Regards,
> >
> >    --
> >
> >    Gilles
> >
> >
> >
> >
> >
> >
>
>
> > _______________________________________________
> > Docutils-users mailing list
> > Doc...@li...
> > https://lists.sourceforge.net/lists/listinfo/docutils-users
> >
> > Please use "Reply All" to reply to the list.
>
>
> --
>
> Dave Kuhlman
> http://www.davekuhlman.org
>
>
> _______________________________________________
> Docutils-users mailing list
> Doc...@li...
> https://lists.sourceforge.net/lists/listinfo/docutils-users
>
> Please use "Reply All" to reply to the list.

Re: [Docutils-users] rst2odt and odf-config-file option

[Dave K. <dku...@da...>]

Gilles,

Ugh.  Did I really do that?

Thanks for this fix.

I'll do some testing and will check the unit tests.  Then I'll push
it back to the repo.

Question for the docutils list: When I apply the `flake8` style and
error checker to `__init__.py`, I get lots of warnings (405 when I
count them with `wc`).  Most of them have to do with indentation,
missing or extra blank lines, missing or extra spaces, etc.  I'm
willing to clean those up.  Or, would that amount of changes be too
disruptive (for example, in making svn history less useful)?  Anyone
have an opinion?  Clean it up?  Leave it alone?  If I do it, I'll
make an extra check-in with only those cleanup changes.

Dave K

On Thu, Feb 07, 2019 at 01:48:42PM +0100, POIRET via Docutils-users wrote:
>    Hello,
> 
>    I guess I've found a bug on rst2odt.py
> 
>    --
> 
>    I wanted to apply custom style with rst2odt, and discovered the
>    --odf-config-file option.
> 
>    This option allows to map the default style to a custom one (so, used in
>    conjunction with --template option).
> 
>    But it was not working on my environment (Debian 9, python3, docutils 1.4)
> 
>    --
> 
>    The __init__ method (l. 888) of the ODFTranslator class initializes a
>    dictionary : format_map, but it's filled only for python2
> 
>    Involved file:
>    /usr/lib/python3/dist-packages/docutils/writers/odf_odt/__init__.py
> 
>           parser = ConfigParser()
>                parser.read(self.settings.odf_config_file)
>                for rststyle, format in parser.items("Formats"):
>                    if rststyle not in self.used_styles:
>                        self.document.reporter.warning(
>                            'Style "%s" is not a style used by odtwriter.' % (
>                                rststyle, ))
>                    if sys.version_info.major == 2:
>                        self.format_map[rststyle] = format.decode('utf-8')
>                   # my addition below
> 
>                   else:
>                        self.format_map[rststyle] = format
> 
>    ---
> 
>  After applying my update, it works. (never tested with python2)
> 
> 
>    Let me know if I can do something else.
> 
>    Regards,
> 
>    --
> 
>    Gilles
> 
>     
> 
>     
> 
>     


> _______________________________________________
> Docutils-users mailing list
> Doc...@li...
> https://lists.sourceforge.net/lists/listinfo/docutils-users
> 
> Please use "Reply All" to reply to the list.


-- 

Dave Kuhlman
http://www.davekuhlman.org

[Docutils-users] rst2odt and odf-config-file option

[POIRET <gil...@bz...>]

Hello, 

I guess I've found a bug on rst2odt.py 

-- 

I wanted to
apply custom style with rst2odt, and discovered the --odf-config-file
option. 

This option allows to map the default style to a custom one
(so, used in conjunction with --template option). 

But it was not
working on my environment (Debian 9, python3, docutils 1.4) 

-- 

The
__init__ method (l. 888) of the ODFTranslator class initializes a
dictionary : format_map, but it's filled only for python2 

Involved
file:
/usr/lib/python3/dist-packages/docutils/writers/odf_odt/__init__.py 

  
   parser = ConfigParser()
           
parser.read(self.settings.odf_config_file)
            for rststyle,
format in parser.items("Formats"):
                if rststyle not in
self.used_styles:
                    self.document.reporter.warning(
  
                    'Style "%s" is not a style used by odtwriter.' % (

                          rststyle, ))
                if
sys.version_info.major == 2:
                   
self.format_map[rststyle] = format.decode('utf-8')
               # my
addition below 

               else:
                   
self.format_map[rststyle] = format 

---

After applying my update, it
works. (never tested with python2)

Let me know if I can do something
else. 

Regards, 

-- 

Gilles 

  

Re: [Docutils-users] How to break up long URLs

[Guenter M. <mi...@us...>]

On 2018-10-11, Gregory Elkinbard wrote:

> Hi folks,

> I have URLs which are longer then 79 characters, how do I break them up
> in docutils compliant manner. I tried “\cr” but this results in an
> error.

You can insert linebreaks in the link target::

  test_
  
  .. _test: http://exam
            ple.org
          
results in the pseudoxml output ::

  <document source="/tmp/url.rst">
      <paragraph>
          <reference name="test" refuri="http://example.org">
              test
      <target ids="test" names="test" refuri="http://example.org">

with the line break and leading whitespace removed from the URL.


Günter

[Docutils-users] How to break up long URLs

[Gregory E. <gel...@ju...>]

Hi folks,
I have URLs which are longer then 79 characters, how do I break them up in docutils compliant manner.
I tried “\cr” but this results in an error.

Thanks
Greg

Re: [Docutils-users] include :code: eats tabs

[Guenter M. <mi...@us...>]

Dear Chris,

On 2018-08-28, Chris Pickel wrote:

> [-- Type: text/plain, Encoding: quoted-printable --]

> I tried using the “include” directive with :code: and :tab-width: -1.
> For some reason, all of the tabs disappeared.
...
> If I remove :tab-width: -1, Pygments no longer detects the tabbed
> lines as errors, but the quoted output still can’t be copy-pasted, as
> hard tabs are required in Makefiles.

Thank you for reporting the problem. Indeed, negative values for the
"tab-width" option work only with files included as "literal".
This restriction is currently not documented in 
http://docutils.sourceforge.net/docs/ref/rst/directives.html#including-an-external-document-fragment

Literal tabs can be preserved in "code" inclusions, too ---
please try the following patch for the directive code:

diff --git a/trunk/docutils/docutils/parsers/rst/directives/misc.py b/trunk/docutils/docutils/parsers/rst/directives/misc.py
index 638974230..fab450a6d 100644
--- a/trunk/docutils/docutils/parsers/rst/directives/misc.py
+++ b/trunk/docutils/docutils/parsers/rst/directives/misc.py
@@ -144,6 +144,9 @@ class Include(Directive):
             return [literal_block]
         if 'code' in self.options:
             self.options['source'] = path
+            # Convert tabs to spaces, if `tab_width` is negative.
+            if tab_width < 0:
+                include_lines = rawtext.splitlines()
             codeblock = CodeBlock(self.name,
                                   [self.options.pop('code')], # arguments
                                   self.options,


LaTeX ignores leading whitespace, so the following is a workaround to
get a visible representation of literal tabs in LaTeX-generated PDF (there
is no easy way to achieve preservation of TAB characters in drag and drop
from the PDF, though).

diff --git a/trunk/docutils/docutils/writers/latex2e/__init__.py b/trunk/docutils/docutils/writers/latex2e/__init__.py
index 0463e3504..fafab2c34 100644
--- a/trunk/docutils/docutils/writers/latex2e/__init__.py
+++ b/trunk/docutils/docutils/writers/latex2e/__init__.py
@@ -1516,6 +1516,10 @@ class LaTeXTranslator(nodes.NodeVisitor):
                 table[ord('>')] = ur'\textgreater{}'
         if self.insert_non_breaking_blanks:
             table[ord(' ')] = ur'~'
+            # tab chars may occur in included files (literal or code)
+            # quick-and-dirty replacement with spaces
+            # (for better results use `--literal-block-env=lstlisting`)
+            table[ord('\t')] = u'~' * self.settings.tab_width
         # Unicode replacements for 8-bit tex engines (not required with XeTeX/LuaTeX):
         if not self.is_xetex:
             if not self.latex_encoding.startswith('utf8'):

sincerely,

Günter

Re: [Docutils-users] How to keep paragraphs or table rows together

[Guenter M. <mi...@us...>]

On 2018-08-30, R. Diez via Docutils-users wrote:

>> as this, keeping paragraphs and tables together, is a layout
>> problem and therefore is depending on the output format,
>> it actually is nothing docutils, or AsciiDoc could or should do.
>> [...]

> I do not understand this point of view. This is a basic feature.
> Without it, documents look unprofessional.

It ist, however, a basic *layout* feature for page-based layouts.

> Even CSS, arguably designed primarily for screen usage, offers more
> control. See "page-break-inside: avoid", which you can add inside HTML.

CSS is a layout description language. You can use CSS with Docutils to style
the output accordingly.





> When the browser renders the page on the screen, it ignores it. When it
> prints it, or generates PDFs, it honours it. And that is independent of
> the output format.

> docutils or AsciiDoc should offer some sort of standard mark-up for
> this. Even if it is in a subset considered "simple layout". The
> distinction between plain information and layout gets a little blurry
> at this point. One could think of "keep together" as a kind of "these
> elements are semantically closer".

There are several ways to convey the semantic of "keep together" in
reStructuredText. It depends on your special need to find out which is
best suited.

> The whole point of such markup languages is that you have a single
> source for many different output formats. However, PDF documents and
> e-book readers have pages, and still are very popular output formats.
> If you need to use different tags depending on the output format for
> such simple matters, the promise of output format independence breaks.

Indeed. However, you still need different stylesheets for the conversion of
the semantic information in the rST source into a layout in, e.g.
LaTeX-generated PDF or HTML for an ebook reader.

Sincerely,

Günter

Re: [Docutils-users] How to keep paragraphs or table rows together

[R. D. <rdi...@ya...>]

> as this, keeping paragraphs and tables together, is a layout
> problem and therefore is depending on the output format,
> it actually is nothing docutils, or AsciiDoc could or should do.
> [...]

I do not understand this point of view. This is a basic feature. Without it, documents look unprofessional.


Even CSS, arguably designed primarily for screen usage, offers more control. See "page-break-inside: avoid", which you can add inside HTML. When the browser renders the page on the screen, it ignores it. When it prints it, or generates PDFs, it honours it. And that is independent of the output format.

docutils or AsciiDoc should offer some sort of standard mark-up for this. Even if it is in a subset considered "simple layout". The distinction between plain information and layout gets a little blurry at this point. One could think of "keep together" as a kind of "these elements are semantically closer".


The whole point of such markup languages is that you have a single source for many different output formats. However, PDF documents and e-book readers have pages, and still are very popular output formats. If you need to use different tags depending on the output format for such simple matters, the promise of output format independence breaks.


Best regards,
  rdiez

Re: [Docutils-users] How to keep paragraphs or table rows together

[R. D. <rdi...@ya...>]

> With respect to LibreOffice and ODF files,
> [...]

The underlying problem is that LibreOffice only offers very limited page break control. As far as I know, this applies to Microsoft Word too. There are just options "do not split paragraph" and "keep with next paragraph", but those are not enough. See here for more information:

Add new feature of 'keep with previous paragraph' formatting option for Writer
https://bugs.documentfoundation.org/show_bug.cgi?id=64795


In fact, what you really need is some visible marker like <begin keep together in page> and <end keep together in page>. Marking single objects in an invisible is fiddly. Just add a new element later and watch your paging break again.

Even CSS, arguably designed primarily for screen usage, offers more control. See "page-break-inside: avoid".

Regards,
  rdiez

Re: [Docutils-users] How to keep paragraphs or table rows together

[Dave K. <dku...@da...>]

With respect to LibreOffice and ODF files, something analogous to
what Engelbert says about latex can be said about the generation of
ODF files for LibreOffice Writer.  After you have used rst2odt.py to
translate your reST doc into an ODF file, you can open that file in
LibreOffice Writer and control orphans and widows by setting
paragraph styles.  Look under menu item:

    Format --> Paragraph ... --> Text flow

Then look for orphan and widow control, and also look for "Do not
split paragraph" and "Keep with next paragraph".

Or, click on:

   Styles --> Styles and Formatting

And, edit the default paragraph style.

And, if you work at it a bit and follow the rst2odt.py
documentation, you can likely create a style-sheet (document) that
initializes the orphan and widow options etc. the way you'd like.
See the following for information about that:
http://docutils.sourceforge.net/docs/user/odt.html#defining-and-using-a-custom-stylesheet

Dave


On Wed, Aug 29, 2018 at 10:07:12PM +0200, engelbert gruber wrote:
>    as this, keeping paragraphs and tables together, is a layout problem and
>    therefore is depending on the output format, it actually is nothing
>    docutils, or AsciiDoc could or should do. Docutils is no typesetter, that
>    would be the browser in the case of html, in which case the "page"-size is
>    volatile.
>    I would go for latex. latex is a system to produce correctly set
>    documents.
>    You can tweak the output by providing a your specific latex preamble
>    and in worst cases you have to change the text
>    i do not think roff is easier or better, although roff is smaller and
>    faster.
>    all the best
>    On Tue, 28 Aug 2018 at 10:19, R. Diez via Docutils-users
>    <doc...@li...> wrote:
> 
>      Hi there:
> 
>      I am evaluating reStructuredText for my documentation needs.
> 
>      The one thing that bothers me most often with Microsoft Word or
>      LibreOffice Writer is that paragraphs or tables are not kept together
>      when generating a PDF or printing. Not everyone can always read the docs
>      on a screen. It looks unprofessional when a page break comes at the
>      wrong time.
> 
>      I haven't learnt much about reStructuredText yet, but I could not
>      (quickly) find a way to mark paragraphs or tables to be kept together on
>      a page.
> 
>      For more detailed information about why I need an easy, consistent way
>      for this kind of thing, check out the following discussion about
>      AsciiDoc, which, in my opinion, does not fit the bill in this respect:
> 
>      How to keep paragraphs or table rows together in a consistent manner
> 
>      https://groups.google.com/forum/#!topic/asciidoc/5TA3SzU0W84
> 
>      Thanks in advance,
>        rdiez
> 
>      ------------------------------------------------------------------------------
>      Check out the vibrant tech community on one of the world's most
>      engaging tech sites, Slashdot.org! http://sdm.link/slashdot
>      _______________________________________________
>      Docutils-users mailing list
>      Doc...@li...
>      https://lists.sourceforge.net/lists/listinfo/docutils-users
> 
>      Please use "Reply All" to reply to the list.

> ------------------------------------------------------------------------------
> Check out the vibrant tech community on one of the world's most
> engaging tech sites, Slashdot.org! http://sdm.link/slashdot

> _______________________________________________
> Docutils-users mailing list
> Doc...@li...
> https://lists.sourceforge.net/lists/listinfo/docutils-users
> 
> Please use "Reply All" to reply to the list.


-- 

Dave Kuhlman
http://www.davekuhlman.org

Re: [Docutils-users] How to keep paragraphs or table rows together

[engelbert g. <eng...@gm...>]

as this, keeping paragraphs and tables together, is a layout problem and
therefore is depending on the output format, it actually is nothing
docutils, or AsciiDoc could or should do. Docutils is no typesetter, that
would be the browser in the case of html, in which case the "page"-size is
volatile.

I would go for latex. latex is a system to produce correctly set documents.
You can tweak the output by providing a your specific latex preamble
and in worst cases you have to change the text

i do not think roff is easier or better, although roff is smaller and
faster.

all the best


On Tue, 28 Aug 2018 at 10:19, R. Diez via Docutils-users <
doc...@li...> wrote:

> Hi there:
>
> I am evaluating reStructuredText for my documentation needs.
>
> The one thing that bothers me most often with Microsoft Word or
> LibreOffice Writer is that paragraphs or tables are not kept together when
> generating a PDF or printing. Not everyone can always read the docs on a
> screen. It looks unprofessional when a page break comes at the wrong time.
>
> I haven't learnt much about reStructuredText yet, but I could not
> (quickly) find a way to mark paragraphs or tables to be kept together on a
> page.
>
> For more detailed information about why I need an easy, consistent way for
> this kind of thing, check out the following discussion about AsciiDoc,
> which, in my opinion, does not fit the bill in this respect:
>
> How to keep paragraphs or table rows together in a consistent manner
>
> https://groups.google.com/forum/#!topic/asciidoc/5TA3SzU0W84
>
> Thanks in advance,
>   rdiez
>
>
> ------------------------------------------------------------------------------
> Check out the vibrant tech community on one of the world's most
> engaging tech sites, Slashdot.org! http://sdm.link/slashdot
> _______________________________________________
> Docutils-users mailing list
> Doc...@li...
> https://lists.sourceforge.net/lists/listinfo/docutils-users
>
> Please use "Reply All" to reply to the list.
>

[Docutils-users] How to keep paragraphs or table rows together

[R. D. <rdi...@ya...>]

Hi there:

I am evaluating reStructuredText for my documentation needs.

The one thing that bothers me most often with Microsoft Word or LibreOffice Writer is that paragraphs or tables are not kept together when generating a PDF or printing. Not everyone can always read the docs on a screen. It looks unprofessional when a page break comes at the wrong time.

I haven't learnt much about reStructuredText yet, but I could not (quickly) find a way to mark paragraphs or tables to be kept together on a page.

For more detailed information about why I need an easy, consistent way for this kind of thing, check out the following discussion about AsciiDoc, which, in my opinion, does not fit the bill in this respect:

How to keep paragraphs or table rows together in a consistent manner

https://groups.google.com/forum/#!topic/asciidoc/5TA3SzU0W84

Thanks in advance,
  rdiez

[Docutils-users] include :code: eats tabs

[Chris P. <sf...@tw...>]

I tried using the “include” directive with :code: and :tab-width: -1.
For some reason, all of the tabs disappeared. The attached example
demonstrates this by including a Makefile. Here’s the output:
https://files.twotaled.com/sf...@tw.../www/rst-tabs/out.html

If I remove :tab-width: -1, Pygments no longer detects the tabbed
lines as errors, but the quoted output still can’t be copy-pasted, as
hard tabs are required in Makefiles.

The inputs, for quick viewing:
https://files.twotaled.com/sf...@tw.../www/rst-tabs/doc.rst
https://files.twotaled.com/sf...@tw.../www/rst-tabs/Makefile

My system information:
Darwin joyeuse.local 17.7.0 Darwin Kernel Version 17.7.0: Thu Jun 21
22:53:14 PDT 2018; root:xnu-4570.71.2~1/RELEASE_X86_64 x86_64
rst2html.py (Docutils 0.14, Python 3.6.5, on darwin)

Re: [Docutils-users] how to present commandline output

[Guenter M. <mi...@us...>]

On 2018-08-09, Glyn Davies wrote:

> Hi Folks,

> I am looking for a a way to include linux commandline output into my
> RST/Sphinx documentation.

> The issue is with random indentation and line length and while I can
> trim the lines it spoils the readability of the output and removing the
> indentation completely screws the context. Below is an example of the
> kind of thing I would like to include if possible.

The usual way to do this would be a `literal block`__. If the content resides
in an external file, use `include`__ with the "literal" option.
This keeps the formatting as-is and uses a fixed-width font.

As a downside, you will evt. see very long lines (overrunning the page in
LaTeX output, requiring scrolling in HTML). If this is a one-off, you
could manually break overfull lines in the rST source. In HTML, you may
solve this via CSS (separate side-scrolling for a fixed-width
literal-block element).

__ http://docutils.sf.net/docs/user/rst/quickref.html#literal-blocks
__ http://docutils.sf.net/docs/ref/rst/directives.html#including-an-external-document-fragment

`Class arguments`__ may be used to scale down the font size of blocks
with too long lines.

http://docutils.sf.net/docs/ref/rst/directives.html#class

Your example contains line breaks that are probably from the terminal. Maybe
using a full-screen terminal to capture the output helps.


Hope this gets you started,

Günter

[Docutils-users] how to present commandline output

[Glyn D. <gly...@ca...>]

Hi Folks,

I am looking for a a way to include linux commandline output into my
RST/Sphinx documentation.

The issue is with random indentation and line length and while I can
trim the lines it spoils the readability of the output and removing the
indentation completely screws the context. Below is an example of the
kind of thing I would like to include if possible.

Cheers,
Glyn


Name:                                   helloworld-deployment
Namespace:                        default
CreationTimestamp:       Mon, 16 Jul 2018 15:32:11 +1200
Labels:                                 app=helloworld
Annotations:                     deployment.kubernetes.io/revision=2
Selector:                              app=helloworld
Replicas:                              6 desired | 6 updated | 6 total
| 6 available | 0 unavailable
StrategyType:                   RollingUpdate
MinReadySeconds:         20
RollingUpdateStrategy:  1 max unavailable, 1 max surge
Pod Template:
  Labels:  app=helloworld
  Containers:
    helloworld:
    Image:        chelios/helloworld-flask:latest
    Port:         5000/TCP
    Host Port:    0/TCP
    Environment:  <none>
    Mounts:       <none>
  Volumes:        <none>
Conditions:
  Type           Status  Reason
  ----           ------  ------
  Available      True    MinimumReplicasAvailable
  Progressing    True    NewReplicaSetAvailable
OldReplicaSets:  <none>
NewReplicaSet:   helloworld-deployment-5896b9988 (6/6 replicas created)
Events:
  Type    Reason             Age   From                   Message
  ----    ------             ----  ----                   -------
  Normal  ScalingReplicaSet  6m    deployment-controller Scaled up
replica set helloworld-deployment-58d59d965b to 3
  Normal  ScalingReplicaSet  2m    deployment-controller Scaled up
replica set helloworld-deployment-58d59d965b to 6
  Normal  ScalingReplicaSet  2m    deployment-controller Scaled up
replica set helloworld-deployment-5896b9988 to 1
  Normal  ScalingReplicaSet  2m    deployment-controller Scaled down
replica set helloworld-deployment-58d59d965b to 5
  Normal  ScalingReplicaSet  2m    deployment-controller Scaled up
replica set helloworld-deployment-5896b9988 to 2
  Normal  ScalingReplicaSet  2m    deployment-controller Scaled down
replica set helloworld-deployment-58d59d965b to 3
  Normal  ScalingReplicaSet  2m    deployment-controller Scaled up
replica set helloworld-deployment-5896b9988 to 4
  Normal  ScalingReplicaSet  1m    deployment-controller Scaled down
replica set helloworld-deployment-58d59d965b to 1
  Normal  ScalingReplicaSet  1m    deployment-controller Scaled up
replica set helloworld-deployment-5896b9988 to 6
  Normal  ScalingReplicaSet  1m    deployment-controller (combined from
similar events): Scaled down replica set helloworld-deployment-
58d59d965b to 0

Re: [Docutils-users] Avoid writer sections for every heading (odt)

[Xavier P. <xpe...@gm...>]

Opps, apologizes, it's shown in the Help.


On 03/08/18 18:25, Xavier Pegenaute wrote:
> Dear,
>
> is there any way to do not create a section per ReST heading while 
> converting to ODT ?
>
> Regards,
>
> Xavi
>
>

[Docutils-users] Avoid writer sections for every heading (odt)

[Xavier P. <xpe...@gm...>]

Dear,

is there any way to do not create a section per ReST heading while 
converting to ODT ?

Regards,

Xavi

Re: [Docutils-users] Internationalization

[george b. <bo...@gm...>]

2018-08-03 18:04 GMT+03:00 David Goodger <go...@py...>:
> You can also inject language modules from your custom tool:
>
>     # appropriate imports here
>     docutils.parsers.rst.languages._languages[language_code] =
> input_language_module
>     docutils.languages._languages[language_code] = output_language_module

Thanks David, I really appreciate your reply. This will do it.

Re: [Docutils-users] Internationalization

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

There are actually two places for language/translation modules: one
for input (docutils/parsers/rst/languages/) and one for output
(docutils/languages/). For this info and other background &
instructions, please read "Docutils Internationalization":
http://docutils.sourceforge.net/docs/howto/i18n.html

The easiest way to develop new language modules is in-situ. Just put
the new modules in the appropriate directories; edit and test them
from there. You can also inject language modules from your custom
tool::

    # appropriate imports here
    docutils.parsers.rst.languages._languages[language_code] =
input_language_module
    docutils.languages._languages[language_code] = output_language_module

When you have completed the new language modules, please send them in
and we'll add them to Docutils!

David Goodger
<https://david.goodger.org>


On Fri, 3 Aug 2018 at 05:23, george boukeas <bo...@gm...> wrote:
>
> Hello everyone.
>
> I hope you can help me with a question: I am writing a custom tool
> that parses reST in HTML and I need the output to be in a language
> that is not currently supported, i.e. it is not in docutils/languages.
> As far as I can tell from reading the code, docutils only checks in
> docutils/languages for translation files. There doesn't seem to be a
> way for me to specify that it should also check some local user
> directory for the appropriate <language>.py file.
>
> So, is there any way to accomplish this?
>
> Thank you very much.
>
> -- George Boukeas.

[Docutils-users] Internationalization

[george b. <bo...@gm...>]

Hello everyone.

I hope you can help me with a question: I am writing a custom tool
that parses reST in HTML and I need the output to be in a language
that is not currently supported, i.e. it is not in docutils/languages.
As far as I can tell from reading the code, docutils only checks in
docutils/languages for translation files. There doesn't seem to be a
way for me to specify that it should also check some local user
directory for the appropriate <language>.py file.

So, is there any way to accomplish this?

Thank you very much.

-- George Boukeas.

Re: [Docutils-users] emacs can't create index

[Stefan M. <st...@me...>]

Hi Ed!

Yesterday Ed Brunelle wrote:
> Anyway, I m back on emacs to edit my rst docs, thanks to a friend I
> discovered that I don't need really to have the TOC on the top of the
> screen.

That is what I thought all the time.

> I can use the C-t C-t to quick navigate to the entries, all i wanted
> the TOC is when I have the rst files exported as HTML, a python util
> called rst2htl
> puts automatically a TOC on the top of each HTML file.

Exactly. These are reasons why I consider this function superfluous.
May be I should remove it entirely.


						Grüße

						Stefan

Re: [Docutils-users] emacs can't create index

[Ed B. <edm...@gm...>]

Hi,

Guys, thank you for the help, I really appreciate it.

Well, as I read on the current online manual  (its just covers the v
1.4.1 I could not find anything newer than this)
(http://docutils.sourceforge.net/docs/user/emacs.html)
the command rst-toc-update
" will automatically update an inserted table of contents following a
.. contents:: directive laid out like the example above."

I assume then its a bug, or this is not working on emacs under
windows. as the rst-toc-update  -in my case- the toc produces
duplicate lines
on its entries, indeed it refreshes the TOC, but usually the last
entries of it are duplicated all the time. Stefan i will try to record
a session of my scree to email it to you/

Anyway, I m back on emacs to edit my rst docs, thanks to a friend I
discovered that I don't need really to have the TOC on the top of the
screen.
I can use the C-t C-t to quick navigate to the entries, all i wanted
the TOC is when I have the rst files exported as HTML, a python util
called rst2htl
puts automatically a TOC on the top of each HTML file.

kind regards

Ed

On Sun, 22 Jul 2018 at 14:19, Stefan Merten <st...@me...> wrote:
>
> Hi Ed!
>
> Yesterday Ed Brunelle wrote:
> > On doing more tests, I am sorry to say that the toc update function is
> > not working as supposed to be.
>
> So what is it supposed to work like? You seem to know it while I as
> the maintainer do not. May be you can help me out? I'd be grateful.
>
> There are a couple of other functions around tocs which IMHO are far
> more useful. For instance try C-c C-t C-t (rst-toc). That is what I am
> using all the time for navigating in a long document.
>
> > looks like emacs + rst == failure, I am shifting my work to vim , bit
> > PITA but rst works better now.
>
> AFAICS you tried one function. Indeed the one which I consider a PITA
> and from my point of view could be removed without anyone noticing.
>
> I'd say the rest of `rst.el` works like a charm and frankly through
> all the years I can't remember any such complaint.
>
>
>                                                 Grüße
>
>                                                 Stefan
>
> ------------------------------------------------------------------------------
> Check out the vibrant tech community on one of the world's most
> engaging tech sites, Slashdot.org! http://sdm.link/slashdot
> _______________________________________________
> Docutils-users mailing list
> Doc...@li...
> https://lists.sourceforge.net/lists/listinfo/docutils-users
>
> Please use "Reply All" to reply to the list.