From: Roberto A. <ra...@ne...> - 2010-06-21 21:29:23
|
Issue 329 has been reported asking that rst2pdf align the caption and the legend of figures following the :align: option of the figure, so in this case:: .. figure:: empty.jpg :align: right caption legend caption and legend should appear right-aligned. * Currently rst2pdf keeps those centered. * The HTML writer seems to align everything to the right. * The LaTeX writer... I don't quite know what it's doing, it seems to completely ignore :align: for the image, and the legend is not centered but somehow left-shifted compared to the centered caption. See http://is.gd/cY7g5 So, my question is... is the rst2latex's behaviour better than rst2html's? Worse? Expected? a bug? What would you think the right behaviour for rst2pdf would be? I think I can go either way, but I don't want to go against convention. |
From: David G. <go...@py...> - 2010-06-21 22:07:53
|
On Mon, Jun 21, 2010 at 17:04, Roberto Alsina <ra...@ne...> wrote: > Issue 329 has been reported asking that rst2pdf align the caption and the > legend of figures following the :align: option of the figure, so in this > case:: > > .. figure:: empty.jpg > :align: right > > caption > > legend > > caption and legend should appear right-aligned. Per http://docutils.sourceforge.net/docs/ref/rst/directives.html#figure, figure's align option governs "The horizontal alignment of the figure, allowing the image to float and have the text flow around it." This is describing the overall figure's alignment on the page (the alignment on the page of the box containing the image, caption, etc.). The layout of the contents of the box are not specified. What you do within the box is up to you. There's no right answer, and there are no interior controls. > * Currently rst2pdf keeps those centered. I prefer this, personally. > * The HTML writer seems to align everything to the right. It's not wrong, but I think it should be aligning only the box the figure is in, and leaving the caption/legend centered or left-aligned. > * The LaTeX writer... I don't quite know what it's doing, it seems to > completely ignore :align: for the image, and the legend is not centered but > somehow left-shifted compared to the centered caption. See > > http://is.gd/cY7g5 Your example doesn't show enough context to see what's going on (I'd like to see how it fits in a page full of text). I suspect the legend is left-aligned within the figure's bounding box, which is probably the entire width of the page. > So, my question is... is the rst2latex's behaviour better than rst2html's? > Worse? Expected? a bug? It is a bit jarring, but I can't tell without context. > What would you think the right behaviour for rst2pdf > would be? > > I think I can go either way, but I don't want to go against convention. -- David Goodger <http://python.net/~goodger> |
From: Roberto A. <ra...@ne...> - 2010-06-21 22:47:30
|
On Monday 21 June 2010 19:07:13 you wrote: > On Mon, Jun 21, 2010 at 17:04, Roberto Alsina > > > * The LaTeX writer... I don't quite know what it's doing, it seems to > > completely ignore :align: for the image, and the legend is not centered > > but somehow left-shifted compared to the centered caption. See > > > > http://is.gd/cY7g5 > > Your example doesn't show enough context to see what's going on (I'd > like to see how it fits in a page full of text). I suspect the legend > is left-aligned within the figure's bounding box, which is probably > the entire width of the page. > > > So, my question is... is the rst2latex's behaviour better than > > rst2html's? Worse? Expected? a bug? > > It is a bit jarring, but I can't tell without context. Here's a better example: http://is.gd/cYdS5 Looks like the caption is centered (and :align: does nothing!) and the legend is just a plain paragraph, slightly separated from the rest of the text flow. Here is the rst that generated that output: Lorem ipsum dolor sit amet, consectetur adipiscing elit. Quisque sed adipiscing erat. Pellentesque lobortis erat malesuada ligula commodo non fringilla massa vestibulum. Duis viverra est et libero pellentesque molestie. Maecenas dictum lacus at justo volutpat tempor. Suspendisse in rhoncus lacus. Maecenas in nunc arcu. Class aptent taciti sociosqu ad litora torquent per conubia nostra, per inceptos himenaeos. Nulla facilisi. Sed quis purus vitae dui tristique interdum. Curabitur facilisis ornare cursus. Maecenas luctus, diam et hendrerit malesuada, tellus justo adipiscing est, quis semper dui magna sed nulla. Suspendisse potenti. In magna ligula, adipiscing ac varius vitae, consequat id turpis. Pellentesque lorem nisl, molestie eu bibendum id, viverra eget dolor. .. figure:: images/biohazard.png :align: right :width: 6cm This is the caption. This is the legend. Maecenas blandit malesuada scelerisque. Suspendisse dictum nulla purus. Morbi non ligula felis. Nunc a eleifend justo. Proin porta imperdiet leo ac ultrices. Aenean at mattis leo. Maecenas lobortis libero sed ligula ultrices suscipit. Sed at nunc nec tortor sagittis mattis a vitae dui. Mauris at nisi diam, at adipiscing magna. Nulla porttitor adipiscing porttitor. Pellentesque semper mauris sed felis tempus aliquet. Pellentesque sed neque neque, sed ornare erat. Suspendisse tincidunt ornare eleifend. Vivamus sodales fringilla pretium. Ut volutpat, mauris vel scelerisque ultrices, erat diam volutpat odio, vitae tempus tellus nisi vitae dolor. Praesent tincidunt arcu eget nisl lobortis eu semper felis luctus. Class aptent taciti sociosqu ad litora torquent per conubia nostra, per inceptos himenaeos. Nullam hendrerit dui ligula, in tincidunt orci. Sed et libero vel risus ultricies accumsan vitae at enim. Nam hendrerit consectetur blandit. Phasellus nec odio purus. Nulla sodales elit vel velit viverra varius. Fusce sagittis, sem id tincidunt dignissim, nisi leo faucibus ante, sit amet rhoncus nisi libero sed dui. Sed et lorem ac leo sodales molestie. Pellentesque nisl arcu, pretium vel euismod ac, luctus tempor mauris. Nullam quis orci sem. Aenean aliquam, ipsum id sollicitudin eleifend, felis dolor interdum dui, nec dapibus ligula urna et neque. Aenean egestas lorem ut sapien sodales feugiat. In volutpat auctor velit, ac convallis mi volutpat a. Fusce euismod sapien eget lectus adipiscing sit amet cursus metus facilisis. Aliquam vel urna erat. Sed fringilla neque in purus bibendum in varius ante ultricies. |
From: David G. <go...@py...> - 2010-06-22 03:05:11
|
2010/6/21 Roberto Alsina <ra...@ne...>: > Here's a better example: > > http://is.gd/cYdS5 > > Looks like the caption is centered (and :align: does nothing!) and the legend > is just a plain paragraph, slightly separated from the rest of the text flow. Try :figwidth: instead of :width:. Ideally, the figure should be 6cm wide on the right side of the page, with the text wrapping around it on the left. But I have to punt to the LaTeX-heads. -- David Goodger <http://python.net/~goodger> |
From: Guenter M. <mi...@us...> - 2010-06-22 12:06:50
|
On 2010-06-21, Roberto Alsina wrote: > Issue 329 has been reported asking that rst2pdf align the caption and the > legend of figures following the :align: option of the figure, so in this > case:: > .. figure:: empty.jpg > :align: right > caption > legend > caption and legend should appear right-aligned. > * Currently rst2pdf keeps those centered. > * The HTML writer seems to align everything to the right. If I look at the "Images and Figures" section in the test output docutils/test/functional/expected/standalone_rst_html4css1.html with firefox, the right-aligned figure has its content left-aligned. The relevant source in standard.txt is:: A right-aligned figure: .. figure:: ../../../docs/user/rst/images/biohazard.png :align: right :width: 40 px This is the caption. This is the legend. The legend may consist of several paragraphs. The alignment of image and legend can be customized with CSS as well as with class options, e.g. .. figure:: ../../../docs/user/rst/images/biohazard.png :figclass: align-center :width: 50% This is the caption .. class:: align-center This is the legend. while the alignment of the caption can currently only be globally set (via CSS). > * The LaTeX writer... I don't quite know what it's doing docs/dev/todo.txt says: Missing features ---------------- * support "figwidth" argument for figures. As the 'figwidth' argument is still ignored and the "natural width" of a figure in LaTeX is 100 % of the text width, setting the 'align' argument has currently no effect on the LaTeX output. Placement of the content is governed by the LaTeX configuration (chosen document class and styles) This is described in latex.txt http://docutils.sourceforge.net/docs/user/latex.html#figure-and-table-captions > So, my question is... is the rst2latex's behaviour better than rst2html's? > Worse? Expected? a bug? No, yes, no, yes (missing feature). > What would you think the right behaviour for rst2pdf > would be? You might try and experiment with the attached test (that precedes the changes to the alignment handling in version 0.6). Günter Figures ======= A *figure* is an image with a caption and/or a legend. With page-based output media, figures might float to a different position if this helps the page layout. .. figure:: tintin.png :class: class1 class2 :figclass: figclass1 figclass2 :width: 20 :figwidth: 50 % A figure with no alignment options, the image is 1 cm wide, the figure width is 50 % of the textwidth (currently ignored in LaTeX). Options ------- The "figure" directive supports all options of the "image" directive and passes them on to the contained image. Exception: The "align" option is not passed to the image but set for the figure element. In addition, the following options are recognized: :figwidth: width of the figure (while "width" is passed on to the image) :figclass: class arguments of the figure (while "class" is passed on to the image) Alignment ========= The term "alignment" as property of an object is ambiguous. It could specify: "outside alignment" How to align an object in the surrounding, e.g. the figure in the body/page/sidebar/... "inside alignment" How to align the content of an object, e.g. the image, caption and legend in the figure. In Docutils, the alignment option of a figure or image specifies the "outside alignment" (see `figure directive`_). However, in version 0.5, the 'align' argument of a figure is applied to the figures content (in contrast to the description). Fix === * keep arguments as: ========== ======= Figure Image ---------- ------- figclass class figwidth width align ========== ======= * Fix HTML rendering of "aligned" figures: * change to the HTML writer's visit_figure method:: - atts['align'] = node['align'] + atts['class'] += " align-" + node['align'] * new CSS rules to get desired layout. * No special argument to specify alignment of objects inside a figure ("inner alignment"). Instead use class arguments and CSS Example: Right-align the figure elements with:: .. figure:: tintin.png :class: align-right caption-align-right A (left aligned) figure with right-aligned image. .. class:: align-right Right aligned legend. Note: There is currently no rule for "caption-align-right" or similar in the default CSS style sheet. Test ==== An image, left, center, and right aligned: .. image:: tintin.png :align: left This paragraph might flow around the image. If it does or not, depends on the style, the output format and the viewer. .. image:: tintin.png :align: center This paragraph might flow around the image. If it does or not, depends on the style, the output format and the viewer. .. image:: tintin.png :align: right This paragraph might flow around the image. If it does or not, depends on the style, the output format and the viewer. A figure: .. figure:: tintin.png :figclass: figclass1 figclass2 :align: left A figure with ``:align: left`` This is the legend. The legend may consist of several paragraphs. This paragraph might flow around the figure. If it does or not, depends on the style, the output format and the viewer. .. figure:: tintin.png :align: center A figure with ``:align: center`` This is the legend. This paragraph might flow around the figure. If it does or not, depends on the style, the output format and the viewer. .. figure:: tintin.png :align: right :figwidth: 350 A figure with ``:align: right`` and ``:figwidth: 350`` This is the legend. This paragraph might flow around the figure. If it does or not, depends on the style, the output format and the viewer. It is possible to pass a class argument to the legend and image, but not to the caption .. figure:: tintin.png :class: align-center :figwidth: 350 A (left aligned) figure with centered image. .. class:: align-right This legend consists of a paragraph with class argument "align-right". It can be styled with CSS. Trying to left-align the contents of a centered figure: .. figure:: tintin.png :align: center :class: align-left A centered figure with left-aligned image. .. class:: align-left This legend consists of a paragraph with class argument "align-left". It can be styled with CSS. Alternatives ------------ A) Complete the current pair-wise nature of the options: ========== ======= Figure Image ---------- ------- figclass class figwidth width *figalign* align ========== ======= 1. 'align' as argument of the <image> element (like class and width). 2. 'figalign' for the "outside alignment" of the figure. B) reverse the notation: ========== ============ Figure Image ---------- ------------ class *imageclass* width *imagewidth* align *imagealign* ========== ============ 1. 'imagealign' as argument of the <image> element (like class and width). 2. 'align' for the "outside alignment" of the figure. .. _figure directive: http://docutils.sf.net/docutils/docs/ref/rst/directives.html#figure |
From: Roberto A. <ra...@ne...> - 2010-06-22 12:22:42
|
So, if I understand correctly: * :align: is about the figure as a whole, not about the image in the figure * :figwidth: has to be supported so :align: does something visible * :width: is the image width * :figclass: sets a class on the whole figure * :class: sets a class on the image Is this right for docutils 0.6? |
From: Guenter M. <mi...@us...> - 2010-06-23 13:18:51
|
On 2010-06-22, Roberto Alsina wrote: > So, if I understand correctly: > * :align: is about the figure as a whole, not about the image in the figure > * :figwidth: has to be supported so :align: does something visible > * :width: is the image width > * :figclass: sets a class on the whole figure > * :class: sets a class on the image > Is this right for docutils 0.6? According to http://docutils.sourceforge.net/docs/ref/rst/directives.html#figure (and my memory) yes. Günter |
From: Roberto A. <ra...@ne...> - 2010-06-23 13:24:08
|
On Wednesday 23 June 2010 10:18:14 Guenter Milde wrote: > On 2010-06-22, Roberto Alsina wrote: > > So, if I understand correctly: > > > > * :align: is about the figure as a whole, not about the image in the > > figure * :figwidth: has to be supported so :align: does something > > visible * :width: is the image width > > * :figclass: sets a class on the whole figure > > * :class: sets a class on the image > > > > Is this right for docutils 0.6? > > According to > http://docutils.sourceforge.net/docs/ref/rst/directives.html#figure > (and my memory) yes. Thanks, I implemented it that way now. The only functionality hole seems to be that captions can't be styled, since you can't assign a class to them. |
From: Guenter M. <mi...@us...> - 2010-06-25 08:15:18
|
On 2010-06-23, Roberto Alsina wrote: > On Wednesday 23 June 2010 10:18:14 Guenter Milde wrote: >> On 2010-06-22, Roberto Alsina wrote: >> > So, if I understand correctly: >> > >> > * :align: is about the figure as a whole, not about the image in the >> > figure * :figwidth: has to be supported so :align: does something >> > visible * :width: is the image width >> > * :figclass: sets a class on the whole figure >> > * :class: sets a class on the image >> > >> > Is this right for docutils 0.6? >> According to >> http://docutils.sourceforge.net/docs/ref/rst/directives.html#figure >> (and my memory) yes. > Thanks, I implemented it that way now. > The only functionality hole seems to be that captions can't be styled, since > you can't assign a class to them. In CSS, you can give a class to the figure and use the child selector. Günter |