From: Guenter M. <mi...@us...> - 2012-11-19 10:24:43
|
On 2012-11-15, SourceForge.net wrote: > Patches item #3587533 by kirr79 > https://sourceforge.net/tracker/?func=detail&atid=422032&aid=3587533&group_id=38414 ... > Submitted By: Kirill Smelkov (kirr79) > Summary: latex2e: Handle classes for bullet lists ... Dear Kirill, thanks for the patch to the LaTeX writer. > For example authors could customize documents as follows: > .. class:: compact > - item 1 > - item 2 > - item 3 > and expect the writer to apply the class. However, the Docutils documentation makes it clear that handling of class arguments by writers is optional: http://docutils.sourceforge.net/docs/ref/doctree.html#classes > This works for html writer, > but not yet for latex2e/xetex and that's why this patch is here. I agree that support for class arguments in LaTeX can/should be extended to include more useful cases. Docutils already adds a mechanism with the ``DUrole`` command, which could be employed here. Suggestion: handle class arguments for bullet lists similar to block-quotes: +1 simple, +1 applicable to other elements without inflating latex2e/__init__.py nor the generated LaTeX source. Dir: /home/milde/Code/Python/docutils-svn/docutils/docutils/writers/latex2e/ Index: __init__.py =================================================================== --- __init__.py (Revision 7527) +++ __init__.py (Arbeitskopie) @@ -553,7 +553,7 @@ PreambleCmds.inline = r""" % inline markup (custom roles) % \DUrole{#1}{#2} tries \DUrole#1{#2} -\providecommand*{\DUrole}[2]{% +\providecommand{\DUrole}[2]{% \ifcsname DUrole#1\endcsname% \csname DUrole#1\endcsname{#2}% \else% backwards compatibility: try \docutilsrole#1{#2} @@ -1595,8 +1595,12 @@ self.out.append( '%\n\\begin{list}{}{}\n' ) else: self.out.append( '%\n\\begin{itemize}\n' ) + if node['classes']: + self.visit_inline(node) def depart_bullet_list(self, node): + if node['classes']: + self.depart_inline(node) if self.is_toc_list: self.out.append( '\n\\end{list}\n' ) else: The above example would produce the code snippet:: \begin{itemize} \DUrole{compact}{ \item item 1 \item item 2 \item item 3 } \end{itemize} This works as expected with a custom stylesheet defining:: \newcommand{\DUrolecompact}{% > \small% > \itemsep=0pt\parskip=0pt% > } > which makes text a bit smaller and tightens inter-line gaps. > NOTES: * Instead of a new environment definition, the already established mechanism and macro name for custom inline roles is re-used. * The change of the \DUrole definition in line 553 allows for multi-paragraph content. This also fixes multi-paragraph quotes. * the definition of ``\DUrolecompact`` affects **all** elements with the class argument "compact" (if the element is of a type where the LaTeX writer supports class arguments). It may be more safe to define \DUrolecompact like :: \newcommand{\DUrolecompact}[1]{% {\small% \itemsep=0pt\parskip=0pt% #1% }% } (untested). * Alternatively, one could consider a \DUclass macro without argument for styling of environments:: PreambleCmds.class = r""" % class arguments % \DUclass{#1} tries \DUrole#1 \providecommand{\DUclass}[1]{% \ifcsname DUclass#1\endcsname% \csname DUclass#1\endcsname% \fi% }""" +1 simpler than \DUrole -1 new name and function needs extra documentation -1 more preamble code if both, inline elements and block elements have class arguments. * As opinion differs whether a compact list should have a smaller font size or not, I'd rather not add this definition to the LaTeX writer. Feel free to add a "compact-lists.sty" style-sheet to the sandbox stylesheet collection. http://docutils.sourceforge.net/sandbox/stylesheets/ > * There is no \provideenvironment in LaTeX, so plain \newenviroment > is used. This has the disadvantage that it cannot be overwritten, which means it should not be hard-coded in the writer. If you agree to the ideas above, I'll commit the above patch. Thanks again, Günter |
From: Guenter M. <mi...@us...> - 2012-11-21 15:50:00
|
On 2012-11-20, Kirill Smelkov wrote: > On Mon, Nov 19, 2012 at 10:24:12AM +0000, Guenter Milde wrote: >> > Patches item #3587533 by kirr79 >> > https://sourceforge.net/tracker/?func=detail&atid=422032&aid=3587533&group_id=38414 Dear Kirill, >> > For example authors could customize documents as follows: >> > .. class:: compact >> > - item 1 >> > - item 2 >> > - item 3 ... >> > This works for html writer, >> > but not yet for latex2e/xetex and that's why this patch is here. >> I agree that support for class arguments in LaTeX can/should be extended >> to include more useful cases. Docutils already adds a mechanism with the >> ``DUrole`` command, which could be employed here. >> Suggestion: handle class arguments for bullet lists similar to block-quotes: >> +1 simple, >> +1 applicable to other elements without inflating latex2e/__init__.py >> nor the generated LaTeX source. ... >> > NOTES: >> * Instead of a new environment definition, the already established >> mechanism and macro name for custom inline roles is re-used. ... >> * the definition of ``\DUrolecompact`` affects **all** elements with >> the class argument "compact" (if the element is of a type where the >> LaTeX writer supports class arguments). >> It may be more safe to define \DUrolecompact like :: >> \newcommand{\DUrolecompact}[1]{% >> {\small% >> \itemsep=0pt\parskip=0pt% >> #1% >> }% >> } >> (untested). >> * Alternatively, one could consider a \DUclass macro without >> argument for styling of environments:: >> PreambleCmds.class = r""" >> % class arguments: \DUclass{#1} tries \DUclass#1 >> \providecommand{\DUclass}[1]{% >> \ifcsname DUclass#1\endcsname% >> \csname DUclass#1\endcsname% >> \fi% >> }""" >> +1 simpler than \DUrole >> -1 new name and function needs extra documentation >> -1 more preamble code if both, inline elements and block elements >> have class arguments. ... > Thanks for thorough reply. However I feel that reusing DUrole for > handling classes would be inflexible, because when DUrole<class> is in > effect we already are in an environment (itemize in your example) and in > general case one may want to use different environments for different > classes. That is not artificial - I've already had to use my own > environment instead of description for customized fieldlists. This could be remedied by wrapping \DUrole around the environment:: \DUrole{compact}{ \begin{itemize} \item item 1 \item item 2 \item item 3 \end{itemize} } > Imho classed DUrole is good, but it should only complement classed > environments, not replace them. The same for uniformity. ... > It is true that support for classes in writer is optional, but if that > support is there it should be robust, uniform and flexible. And to me that > means we should emit \DUsomething or \DUsomething[class] for `something` > document elements. This is where I disagree: I do not like to have a lot of DUsomething definitions in the latex document's preamble. > I'm also proposing we next convert all direct usage of TeX environments > to DUsomething classed dispatch step-by-step. This blows up the latex source and makes it hard to convert to anything except DVI or PDF. (Think about import to LyX or OpenOffice, e.g.) as well as working on Docutils-generated LaTeX source. Günter |
From: Kirill S. <ki...@mn...> - 2012-11-22 09:11:45
|
On Wed, Nov 21, 2012 at 03:49:29PM +0000, Guenter Milde wrote: > On 2012-11-20, Kirill Smelkov wrote: > > On Mon, Nov 19, 2012 at 10:24:12AM +0000, Guenter Milde wrote: > >> > Patches item #3587533 by kirr79 > >> > https://sourceforge.net/tracker/?func=detail&atid=422032&aid=3587533&group_id=38414 > > Dear Kirill, > > >> > For example authors could customize documents as follows: > > >> > .. class:: compact > > >> > - item 1 > >> > - item 2 > >> > - item 3 > > ... > > >> > This works for html writer, > >> > but not yet for latex2e/xetex and that's why this patch is here. > > >> I agree that support for class arguments in LaTeX can/should be extended > >> to include more useful cases. Docutils already adds a mechanism with the > >> ``DUrole`` command, which could be employed here. > > >> Suggestion: handle class arguments for bullet lists similar to block-quotes: > > >> +1 simple, > >> +1 applicable to other elements without inflating latex2e/__init__.py > >> nor the generated LaTeX source. > > ... > > >> > NOTES: > > >> * Instead of a new environment definition, the already established > >> mechanism and macro name for custom inline roles is re-used. > ... > >> * the definition of ``\DUrolecompact`` affects **all** elements with > >> the class argument "compact" (if the element is of a type where the > >> LaTeX writer supports class arguments). > > >> It may be more safe to define \DUrolecompact like :: > > >> \newcommand{\DUrolecompact}[1]{% > >> {\small% > >> \itemsep=0pt\parskip=0pt% > >> #1% > >> }% > >> } > > >> (untested). > > >> * Alternatively, one could consider a \DUclass macro without > >> argument for styling of environments:: > > >> PreambleCmds.class = r""" > >> % class arguments: \DUclass{#1} tries \DUclass#1 > >> \providecommand{\DUclass}[1]{% > >> \ifcsname DUclass#1\endcsname% > >> \csname DUclass#1\endcsname% > >> \fi% > >> }""" > > >> +1 simpler than \DUrole > >> -1 new name and function needs extra documentation > >> -1 more preamble code if both, inline elements and block elements > >> have class arguments. > > ... > > > Thanks for thorough reply. However I feel that reusing DUrole for > > handling classes would be inflexible, because when DUrole<class> is in > > effect we already are in an environment (itemize in your example) and in > > general case one may want to use different environments for different > > classes. That is not artificial - I've already had to use my own > > environment instead of description for customized fieldlists. > > This could be remedied by wrapping \DUrole around the environment:: > > \DUrole{compact}{ > \begin{itemize} > \item item 1 > > \item item 2 > > \item item 3 > \end{itemize} > } Imho no, this won't work. For example in { \small% \itemsep=0pt\parskip=0pt% \begin{itemize} \item item 1 \item item 2 \item item 3 \end{itemize} } only \small takes the effect, and itemsep and parskip settings do not. This is related to how latex environments work - either you set it's settings inside, or you should know the nesting level and set itemsep<level> and parskip<level> etc, which is not elegantly possible for general wrapper ... Besides, we are hardcoding used environment in stone. I think the consensus here could be as follows: 1. \DUenv[class] looks for \DUenvclass, and uses it if found. 2. if not, fallback environment is used (itemize for DUitemize) with your \DUclass[class] inside it (sorry, I've missed it in a hurry on the first read), e.g. > * Alternatively, one could consider a \DUclass macro without > argument for styling of environments:: > > PreambleCmds.class = r""" > % class arguments > % \DUclass{#1} tries \DUrole#1 > \providecommand{\DUclass}[1]{% > \ifcsname DUclass#1\endcsname% > \csname DUclass#1\endcsname% > \fi% > }""" \begin{itemize} \DUclass[compact] \item ... \end{itemize} This way, if particular classed environment is provided by user stylesheet - all is in that environment control. If not, we still try to do styling via DUclass<class> which definition is not duplicated for all environments. What do you think? ( And also, using DUrole for styling classes could come into confilict with using roles in the document itself, e.g. as in :compact:`text` ) > > Imho classed DUrole is good, but it should only complement classed > > environments, not replace them. The same for uniformity. > > ... > > > It is true that support for classes in writer is optional, but if that > > support is there it should be robust, uniform and flexible. And to me that > > means we should emit \DUsomething or \DUsomething[class] for `something` > > document elements. > > This is where I disagree: I do not like to have a lot of DUsomething > definitions in the latex document's preamble. see below. > > I'm also proposing we next convert all direct usage of TeX environments > > to DUsomething classed dispatch step-by-step. > > This blows up the latex source and makes it hard to convert to anything > except DVI or PDF. (Think about import to LyX or OpenOffice, e.g.) as well > as working on Docutils-generated LaTeX source. This blows up only preamble, which we are maybe better move to separate static file, and add an option for rst2latex to whether embed it or not into generated tex source, just like html writer does with --embed-stylesheet. The document text itself is not blown up, and still remains structured. I see no problem importing it to anywhere, without embedded pramble. Yes, importers should be taught about what used DUenv means, but we already have to do it, because for example we already use \begin{DUfieldlist} ... \end{DUfiledlist}. Thanks, Kirill |
From: Guenter M. <mi...@us...> - 2012-11-22 13:43:16
|
On 2012-11-22, Kirill Smelkov wrote: > On Wed, Nov 21, 2012 at 03:49:29PM +0000, Guenter Milde wrote: Dear Kirill, >> >> I agree that support for class arguments in LaTeX can/should be extended >> >> to include more useful cases. Docutils already adds a mechanism with the >> >> ``DUrole`` command, which could be employed here. >> >> Suggestion: handle class arguments for bullet lists similar to >> >> block-quotes: >> >> +1 simple, >> >> +1 applicable to other elements without inflating latex2e/__init__.py >> >> nor the generated LaTeX source. >> ... >> > Thanks for thorough reply. However I feel that reusing DUrole for >> > handling classes would be inflexible, because when DUrole<class> is in >> > effect we already are in an environment (itemize in your example) and in >> > general case one may want to use different environments for different >> > classes. That is not artificial - I've already had to use my own >> > environment instead of description for customized fieldlists. >> This could be remedied by wrapping \DUrole around the environment:: >> \DUrole{compact}{ >> \begin{itemize} >> \item item 1 >> \item item 2 >> \item item 3 >> \end{itemize} >> } > Imho no, this won't work. ... > This is related to how latex environments work - either you set > it's settings inside, or you should know the nesting level and set > itemsep<level> and parskip<level> etc, which is not elegantly possible > for general wrapper ... I recommend the very nice enumitem_ package for list customization. It's comprehensive documentation reveals that the example problem could be solved via "global settings" where the level-argument is optional :: \documentclass[]{article} \usepackage{lmodern} \usepackage[T1]{fontenc} \usepackage{enumitem} \begin{document} Compact: { \setlist[itemize]{noitemsep} \small% \begin{itemize} \item item 1 \item item 2 \end{itemize} } Back to normal: \begin{itemize} \item item 1 \item item 2 \end{itemize} \end{document} .. _enumitem: http://mirror.ctan.org/help/Catalogue/entries/enumitem.html > Besides, we are hardcoding used environment in stone. Yes, if there is a matching standard environment (or macro), we are using it. IMO this is "the right thing". It provides widely compatible, clean LaTeX files and allows styling with the established LaTeX tools. A stylesheet can even save the original environment or macro to an alias and overwrite the definition with a custom version. > I think the consensus here could be as follows: > 1. \DUenv[class] looks for \DUenvclass, and uses it if found. > 2. if not, fallback environment is used (itemize for DUitemize) with > your \DUclass[class] inside it (sorry, I've missed it in a hurry > on the first read), e.g. ... > What do you think? -1 too complicated. -1 inflating latex2e/__init__.py and the generated LaTeX source. -1 custom macros are cumbersome when hand-editing the LaTeX source or converting it to other source formats. > ( And also, using DUrole for styling classes could come into confilict > with using roles in the document itself, e.g. as in :compact:`text` ) It would be up to the user to ensure that "DUrole..." macros do not interfere. Class arguments and custom styles are advanced stuff, so, IMO, we are not demanding too much. Considering that "compact" is already established in the HTML writer, a different name could be used for the role. In other cases, a class argument like "compactlist" or similar can be used. Also mind, that, e.g. :: \newcommand{\DUrolesmall}[1]{% {\setlist[itemize]{noitemsep}\small#1}% } would work as expected in both, a "small" bullet-list and a :small:`role`. >> > I'm also proposing we next convert all direct usage of TeX environments >> > to DUsomething classed dispatch step-by-step. >> This blows up the latex source and makes it hard to convert to anything >> except DVI or PDF. (Think about import to LyX or OpenOffice, e.g.) as well >> as working on Docutils-generated LaTeX source. > This blows up only preamble, which we are maybe better move to separate > static file, and add an option for rst2latex to whether embed it or not > into generated tex source, just like html writer does with > --embed-stylesheet. This is a separate TODO item: Move the preamble code to a LaTeX package (which should also be uploaded to CTAN) and provide an "embed-stylesheet" setting with possible values: yes, no, and subset (where subset is basically the current behaviour). > The document text itself is not blown up, and still remains structured. > I see no problem importing it to anywhere, without embedded preamble. > Yes, importers should be taught about what used DUenv means, but we > already have to do it, because for example we already use > \begin{DUfieldlist} ... \end{DUfiledlist}. I'd rather get rid of DUfieldlist... Thanks, Günter |
From: Kirill S. <ki...@mn...> - 2012-11-23 10:05:59
|
On Thu, Nov 22, 2012 at 01:42:51PM +0000, Guenter Milde wrote: > On 2012-11-22, Kirill Smelkov wrote: > > On Wed, Nov 21, 2012 at 03:49:29PM +0000, Guenter Milde wrote: > > Dear Kirill, > > >> >> I agree that support for class arguments in LaTeX can/should be extended > >> >> to include more useful cases. Docutils already adds a mechanism with the > >> >> ``DUrole`` command, which could be employed here. > > >> >> Suggestion: handle class arguments for bullet lists similar to > >> >> block-quotes: > > >> >> +1 simple, > >> >> +1 applicable to other elements without inflating latex2e/__init__.py > >> >> nor the generated LaTeX source. > > >> ... > > >> > Thanks for thorough reply. However I feel that reusing DUrole for > >> > handling classes would be inflexible, because when DUrole<class> is in > >> > effect we already are in an environment (itemize in your example) and in > >> > general case one may want to use different environments for different > >> > classes. That is not artificial - I've already had to use my own > >> > environment instead of description for customized fieldlists. > > >> This could be remedied by wrapping \DUrole around the environment:: > > >> \DUrole{compact}{ > >> \begin{itemize} > >> \item item 1 > > >> \item item 2 > > >> \item item 3 > >> \end{itemize} > >> } > > > Imho no, this won't work. > > ... > > > This is related to how latex environments work - either you set > > it's settings inside, or you should know the nesting level and set > > itemsep<level> and parskip<level> etc, which is not elegantly possible > > for general wrapper ... > > I recommend the very nice enumitem_ package for list customization. It's > comprehensive documentation reveals that the example problem could be > solved via "global settings" where the level-argument is optional :: > > \documentclass[]{article} > \usepackage{lmodern} > \usepackage[T1]{fontenc} > > \usepackage{enumitem} > > \begin{document} > > Compact: > > { > \setlist[itemize]{noitemsep} > \small% > \begin{itemize} > \item item 1 > \item item 2 > \end{itemize} > } > > Back to normal: > > \begin{itemize} > \item item 1 > \item item 2 > \end{itemize} > > \end{document} > > > .. _enumitem: > http://mirror.ctan.org/help/Catalogue/entries/enumitem.html > > > > Besides, we are hardcoding used environment in stone. > > Yes, if there is a matching standard environment (or macro), we are using > it. IMO this is "the right thing". It provides widely compatible, clean > LaTeX files and allows styling with the established LaTeX tools. > > A stylesheet can even save the original environment or macro to an alias > and overwrite the definition with a custom version. > > > I think the consensus here could be as follows: > > > 1. \DUenv[class] looks for \DUenvclass, and uses it if found. > > 2. if not, fallback environment is used (itemize for DUitemize) with > > your \DUclass[class] inside it (sorry, I've missed it in a hurry > > on the first read), e.g. > > ... > > > What do you think? > > -1 too complicated. > -1 inflating latex2e/__init__.py and the generated LaTeX source. > -1 custom macros are cumbersome when hand-editing the LaTeX source or > converting it to other source formats. > > > > ( And also, using DUrole for styling classes could come into confilict > > with using roles in the document itself, e.g. as in :compact:`text` ) > > It would be up to the user to ensure that "DUrole..." macros do not > interfere. Class arguments and custom styles are advanced stuff, so, IMO, > we are not demanding too much. > > Considering that "compact" is already established in the HTML writer, a > different name could be used for the role. In other cases, a class argument > like "compactlist" or similar can be used. > > Also mind, that, e.g. :: > > \newcommand{\DUrolesmall}[1]{% > {\setlist[itemize]{noitemsep}\small#1}% > } > > would work as expected in both, a "small" bullet-list and a > :small:`role`. > > > >> > I'm also proposing we next convert all direct usage of TeX environments > >> > to DUsomething classed dispatch step-by-step. > > >> This blows up the latex source and makes it hard to convert to anything > >> except DVI or PDF. (Think about import to LyX or OpenOffice, e.g.) as well > >> as working on Docutils-generated LaTeX source. > > > This blows up only preamble, which we are maybe better move to separate > > static file, and add an option for rst2latex to whether embed it or not > > into generated tex source, just like html writer does with > > --embed-stylesheet. > > This is a separate TODO item: Move the preamble code to a LaTeX package > (which should also be uploaded to CTAN) and provide an > "embed-stylesheet" setting with possible values: yes, no, and subset > (where subset is basically the current behaviour). > > > The document text itself is not blown up, and still remains structured. > > I see no problem importing it to anywhere, without embedded preamble. > > > Yes, importers should be taught about what used DUenv means, but we > > already have to do it, because for example we already use > > \begin{DUfieldlist} ... \end{DUfiledlist}. > > > I'd rather get rid of DUfieldlist... Dear Günter, Maybe you are right, but I think the consensus here is that we disagree. Maybe we have different tastes or whatever, I don't know. It's a pity, but I'm already used to the fact that my patches don't get in and only serve to start discussions. Hope they are somehow, at least, inderectly useful. Unfortunately my current situation does not allow me to spend time on discussions nor I see we are getting near to solutions which I would like. I will try to continue to give back via posting my occasional changes to sourceforge patch tracker. Thats all I can afford myself. > Thanks, > > Günter Thanks for maintaining Docutils, Kirill .--. .--. ._' |/ :.-, | `'.-;-.;` .' _:._/.'.'.'\.`-. / \.'.'.'/ / '-._.;`'-'-';---' , /> jgs / /| \'-. \\/( `--' `-.-' `\|_.-' `\ ' |
From: Guenter M. <mi...@us...> - 2012-12-04 17:48:58
|
Dear Kirill, On 2012-11-23, Kirill Smelkov wrote: > Maybe you are right, but I think the consensus here is that we disagree. > Maybe we have different tastes or whatever, I don't know. > It's a pity, but I'm already used to the fact that my patches don't get > in and only serve to start discussions. Hope they are somehow, at least, > inderectly useful. > Unfortunately my current situation does not allow me to spend time on > discussions nor I see we are getting near to solutions which I would like. I regret that it seems impossible to reconcile our visions of Docutils development but accept your position. > I will try to continue to give back via posting my occasional changes to > sourceforge patch tracker. Thats all I can afford myself. As an alternative, you could also open a sandbox project with an alternative LaTeX writer. This would it make it easier for others to use your version. Thank you for your contributions, Günter |
From: Kirill S. <ki...@mn...> - 2012-11-20 16:47:48
|
(resending without pdf attachment -> please look for it in the issue) Dear Günter, On Mon, Nov 19, 2012 at 10:24:12AM +0000, Guenter Milde wrote: > On 2012-11-15, SourceForge.net wrote: > > Patches item #3587533 by kirr79 > > https://sourceforge.net/tracker/?func=detail&atid=422032&aid=3587533&group_id=38414 > ... > > Submitted By: Kirill Smelkov (kirr79) > > Summary: latex2e: Handle classes for bullet lists > > ... > > Dear Kirill, > > thanks for the patch to the LaTeX writer. > > > For example authors could customize documents as follows: > > > .. class:: compact > > > - item 1 > > - item 2 > > - item 3 > > > and expect the writer to apply the class. > > However, the Docutils documentation makes it clear that handling of class > arguments by writers is optional: > http://docutils.sourceforge.net/docs/ref/doctree.html#classes > > > This works for html writer, > > but not yet for latex2e/xetex and that's why this patch is here. > > I agree that support for class arguments in LaTeX can/should be extended > to include more useful cases. Docutils already adds a mechanism with the > ``DUrole`` command, which could be employed here. > > Suggestion: handle class arguments for bullet lists similar to block-quotes: > > +1 simple, > +1 applicable to other elements without inflating latex2e/__init__.py > nor the generated LaTeX source. > > > Dir: /home/milde/Code/Python/docutils-svn/docutils/docutils/writers/latex2e/ > > Index: __init__.py > =================================================================== > --- __init__.py (Revision 7527) > +++ __init__.py (Arbeitskopie) > @@ -553,7 +553,7 @@ > PreambleCmds.inline = r""" > % inline markup (custom roles) > % \DUrole{#1}{#2} tries \DUrole#1{#2} > -\providecommand*{\DUrole}[2]{% > +\providecommand{\DUrole}[2]{% > \ifcsname DUrole#1\endcsname% > \csname DUrole#1\endcsname{#2}% > \else% backwards compatibility: try \docutilsrole#1{#2} > @@ -1595,8 +1595,12 @@ > self.out.append( '%\n\\begin{list}{}{}\n' ) > else: > self.out.append( '%\n\\begin{itemize}\n' ) > + if node['classes']: > + self.visit_inline(node) > > def depart_bullet_list(self, node): > + if node['classes']: > + self.depart_inline(node) > if self.is_toc_list: > self.out.append( '\n\\end{list}\n' ) > else: > > The above example would produce the code snippet:: > > \begin{itemize} > \DUrole{compact}{ > \item item 1 > > \item item 2 > > \item item 3 > } > \end{itemize} > > > This works as expected with a custom stylesheet defining:: > > > \newcommand{\DUrolecompact}{% > > \small% > > \itemsep=0pt\parskip=0pt% > > } > > > which makes text a bit smaller and tightens inter-line gaps. > > > > NOTES: > > * Instead of a new environment definition, the already established > mechanism and macro name for custom inline roles is re-used. > > * The change of the \DUrole definition in line 553 allows for > multi-paragraph content. This also fixes multi-paragraph quotes. > > * the definition of ``\DUrolecompact`` affects **all** elements with > the class argument "compact" (if the element is of a type where the > LaTeX writer supports class arguments). > > It may be more safe to define \DUrolecompact like :: > > \newcommand{\DUrolecompact}[1]{% > {\small% > \itemsep=0pt\parskip=0pt% > #1% > }% > } > > (untested). > > * Alternatively, one could consider a \DUclass macro without > argument for styling of environments:: > > PreambleCmds.class = r""" > % class arguments > % \DUclass{#1} tries \DUrole#1 > \providecommand{\DUclass}[1]{% > \ifcsname DUclass#1\endcsname% > \csname DUclass#1\endcsname% > \fi% > }""" > > +1 simpler than \DUrole > -1 new name and function needs extra documentation > -1 more preamble code if both, inline elements and block elements > have class arguments. > > * As opinion differs whether a compact list should have a smaller font > size or not, I'd rather not add this definition to the LaTeX > writer. Feel free to add a "compact-lists.sty" style-sheet to the > sandbox stylesheet collection. > http://docutils.sourceforge.net/sandbox/stylesheets/ > > > * There is no \provideenvironment in LaTeX, so plain \newenviroment > > is used. > > This has the disadvantage that it cannot be overwritten, which > means it should not be hard-coded in the writer. > > If you agree to the ideas above, I'll commit the above patch. Thanks for thorough reply. However I feel that reusing DUrole for handling classes would be inflexible, because when DUrole<class> is in effect we already are in an environment (itemize in your example) and in general case one may want to use different environments for different classes. That is not artificial - I've already had to use my own environment instead of description for customized fieldlists. Let's not limit ourselves to compact-lists only, but consider general case where elements may be classed - e.g. field lists, etc... Imho classed DUrole is good, but it should only complement classed environments, not replace them. The same for uniformity. It is true that support for classes in writer is optional, but if that support is there it should be robust, uniform and flexible. And to me that means we should emit \DUsomething or \DUsomething[class] for `something` document elements. I'm saying that all to the fact, that we should not fear introducing visible large changes with e.g. DUitemize. Yes, the change will be large, but in essence it just substitutes DUitemize for itemize for elements without class attribute. So the patch will be well defined and simple. Attaching cleaned up version of the patch (2) to this mail. They are also available here: http://repo.or.cz/w/docutils/kirr.git/shortlog/refs/heads/y/latex-itemize-class I'm also proposing we next convert all direct usage of TeX environments to DUsomething classed dispatch step-by-step. ~~~~ Also in no way I propose we add my compact class to any style - to me it is ugly, because I don't feel like I'm at home when writing TeX styles - it was provided only as an example. Also, regarding lack of \provideenvironment - there is a workaround, and it is already there in latex2e/__init__.py: PreambleCmds.fieldlist = r""" % fieldlist environment \ifthenelse{\isundefined{\DUfieldlist}}{ \newenvironment{DUfieldlist}% {\quote\description} {\enddescription\endquote} }{}""" so we could use the same approach for providing other environments (I'm using it now in the patch). ~~~~ Another example of specialized classes and TeX: For example I use specialized fieldlist environment to typeset revision history, like this (but please again, let's not limit the problem to this one particular example): .. class:: revloghead :Revision: 1.1 (2012-11-20) :Author: K. Smelkov .. class:: compact - edit1 - edit2 - edit3 .. class:: revloghead :Revision: 1.1. (2003-04-25) :Author: S.V. Satsky .. class:: compact - navy start .. class:: revloghead :Revision: 1.0 (1970-01-01) :Author: B.W. Kernighan, D.M. Ritchie .. class:: compact - hello world actually the above example is typeset as .. class:: revlog Revision history ================ :Revision: 1.2 (2012-11-20) :Author: K.V. Smelkov - edit1 - edit2 - edit3 :Revision: 1.1. (2003-04-25) :Author: S.V. Satsky - navy start :Revision: 1.0 (1970-01-01) :Author: B.W. Kernighan, D.M. Ritchie - hello world and custom transform adds revloghead and compact classes for items in sections of class revlog:: class RevLogTransform(Transform): """Пост-обработка разделов с историей изменений Выставляет classes для элементов внутри раздела помеченного как revlog например .. class:: revlog История изменений ----------------- :Редакция: 123 % <- выставит класс revloghead :Автор: Пупкин - сделано то-то и то-то; % <- выставит класс compact - так-то и так-то; Также отделят одну редакцию от другой разделителем. """ default_priority = 850 # XXX ok? def apply(self): for section in self.document.traverse(nodes.section): if not 'revlog' in section['classes']: continue firsthead = True i=0 while i<len(section.children): node = section.children[i] if isinstance(node, nodes.bullet_list): if not node['classes']: node['classes'] += ['compact'] elif isinstance(node, nodes.field_list): if not node['classes']: node['classes'] += ['revloghead'] if 'revloghead' in node['classes']: if firsthead: firsthead = False else: revtransition = latex(r'\bigskip\hrule\bigskip') # XXX section.insert(i, revtransition) i += 1 i += 1 Style for revloghead fieldlists: \newenvironment{DUfieldlistrevloghead}{% \begingroup% \renewcommand{\item}[1][]{% \item[##1]% \ifthenelse{\equal{##1}{Revision:}}{\bf}{\rm}% }% \begin{list}{}{% \itemsep=0pt\parsep=0pt% чтобы строчки шли одна за другой без лишнего vspace % http://www.latex-community.org/forum/viewtopic.php?f=5&t=7607 \renewcommand{\makelabel}[1]{\rm ##1\hfill} \settowidth\labelwidth{\makelabel{Revision: \quad}}% %\setlength\labelwidth{65pt}% \setlength\leftmargin{\labelwidth}% \addtolength\labelwidth{-\labelsep}% % }% }{% \end{list}% \endgroup% } (again this is probably ugly, provided only as example) ~~~~ Sorry, this mail was written in a hurry... Thanks, Kirill |
From: Kirill S. <ki...@mn...> - 2012-11-20 16:50:27
|
Dear Günter, On Mon, Nov 19, 2012 at 10:24:12AM +0000, Guenter Milde wrote: > On 2012-11-15, SourceForge.net wrote: > > Patches item #3587533 by kirr79 > > https://sourceforge.net/tracker/?func=detail&atid=422032&aid=3587533&group_id=38414 > ... > > Submitted By: Kirill Smelkov (kirr79) > > Summary: latex2e: Handle classes for bullet lists > > ... > > Dear Kirill, > > thanks for the patch to the LaTeX writer. > > > For example authors could customize documents as follows: > > > .. class:: compact > > > - item 1 > > - item 2 > > - item 3 > > > and expect the writer to apply the class. > > However, the Docutils documentation makes it clear that handling of class > arguments by writers is optional: > http://docutils.sourceforge.net/docs/ref/doctree.html#classes > > > This works for html writer, > > but not yet for latex2e/xetex and that's why this patch is here. > > I agree that support for class arguments in LaTeX can/should be extended > to include more useful cases. Docutils already adds a mechanism with the > ``DUrole`` command, which could be employed here. > > Suggestion: handle class arguments for bullet lists similar to block-quotes: > > +1 simple, > +1 applicable to other elements without inflating latex2e/__init__.py > nor the generated LaTeX source. > > > Dir: /home/milde/Code/Python/docutils-svn/docutils/docutils/writers/latex2e/ > > Index: __init__.py > =================================================================== > --- __init__.py (Revision 7527) > +++ __init__.py (Arbeitskopie) > @@ -553,7 +553,7 @@ > PreambleCmds.inline = r""" > % inline markup (custom roles) > % \DUrole{#1}{#2} tries \DUrole#1{#2} > -\providecommand*{\DUrole}[2]{% > +\providecommand{\DUrole}[2]{% > \ifcsname DUrole#1\endcsname% > \csname DUrole#1\endcsname{#2}% > \else% backwards compatibility: try \docutilsrole#1{#2} > @@ -1595,8 +1595,12 @@ > self.out.append( '%\n\\begin{list}{}{}\n' ) > else: > self.out.append( '%\n\\begin{itemize}\n' ) > + if node['classes']: > + self.visit_inline(node) > > def depart_bullet_list(self, node): > + if node['classes']: > + self.depart_inline(node) > if self.is_toc_list: > self.out.append( '\n\\end{list}\n' ) > else: > > The above example would produce the code snippet:: > > \begin{itemize} > \DUrole{compact}{ > \item item 1 > > \item item 2 > > \item item 3 > } > \end{itemize} > > > This works as expected with a custom stylesheet defining:: > > > \newcommand{\DUrolecompact}{% > > \small% > > \itemsep=0pt\parskip=0pt% > > } > > > which makes text a bit smaller and tightens inter-line gaps. > > > > NOTES: > > * Instead of a new environment definition, the already established > mechanism and macro name for custom inline roles is re-used. > > * The change of the \DUrole definition in line 553 allows for > multi-paragraph content. This also fixes multi-paragraph quotes. > > * the definition of ``\DUrolecompact`` affects **all** elements with > the class argument "compact" (if the element is of a type where the > LaTeX writer supports class arguments). > > It may be more safe to define \DUrolecompact like :: > > \newcommand{\DUrolecompact}[1]{% > {\small% > \itemsep=0pt\parskip=0pt% > #1% > }% > } > > (untested). > > * Alternatively, one could consider a \DUclass macro without > argument for styling of environments:: > > PreambleCmds.class = r""" > % class arguments > % \DUclass{#1} tries \DUrole#1 > \providecommand{\DUclass}[1]{% > \ifcsname DUclass#1\endcsname% > \csname DUclass#1\endcsname% > \fi% > }""" > > +1 simpler than \DUrole > -1 new name and function needs extra documentation > -1 more preamble code if both, inline elements and block elements > have class arguments. > > * As opinion differs whether a compact list should have a smaller font > size or not, I'd rather not add this definition to the LaTeX > writer. Feel free to add a "compact-lists.sty" style-sheet to the > sandbox stylesheet collection. > http://docutils.sourceforge.net/sandbox/stylesheets/ > > > * There is no \provideenvironment in LaTeX, so plain \newenviroment > > is used. > > This has the disadvantage that it cannot be overwritten, which > means it should not be hard-coded in the writer. > > If you agree to the ideas above, I'll commit the above patch. Thanks for thorough reply. However I feel that reusing DUrole for handling classes would be inflexible, because when DUrole<class> is in effect we already are in an environment (itemize in your example) and in general case one may want to use different environments for different classes. That is not artificial - I've already had to use my own environment instead of description for customized fieldlists. Let's not limit ourselves to compact-lists only, but consider general case where elements may be classed - e.g. field lists, etc... Imho classed DUrole is good, but it should only complement classed environments, not replace them. The same for uniformity. It is true that support for classes in writer is optional, but if that support is there it should be robust, uniform and flexible. And to me that means we should emit \DUsomething or \DUsomething[class] for `something` document elements. I'm saying that all to the fact, that we should not fear introducing visible large changes with e.g. DUitemize. Yes, the change will be large, but in essence it just substitutes DUitemize for itemize for elements without class attribute. So the patch will be well defined and simple. Attaching cleaned up version of the patch (2) to this mail. They are also available here: http://repo.or.cz/w/docutils/kirr.git/shortlog/refs/heads/y/latex-itemize-class I'm also proposing we next convert all direct usage of TeX environments to DUsomething classed dispatch step-by-step. ~~~~ Also in no way I propose we add my compact class to any style - to me it is ugly, because I don't feel like I'm at home when writing TeX styles - it was provided only as an example. Also, regarding lack of \provideenvironment - there is a workaround, and it is already there in latex2e/__init__.py: PreambleCmds.fieldlist = r""" % fieldlist environment \ifthenelse{\isundefined{\DUfieldlist}}{ \newenvironment{DUfieldlist}% {\quote\description} {\enddescription\endquote} }{}""" so we could use the same approach for providing other environments (I'm using it now in the patch). ~~~~ Another example of specialized classes and TeX: For example I use specialized fieldlist environment to typeset revision history, like this (but please again, let's not limit the problem to this one particular example): .. class:: revloghead :Revision: 1.1 (2012-11-20) :Author: K. Smelkov .. class:: compact - edit1 - edit2 - edit3 .. class:: revloghead :Revision: 1.1. (2003-04-25) :Author: S.V. Satsky .. class:: compact - navy start .. class:: revloghead :Revision: 1.0 (1970-01-01) :Author: B.W. Kernighan, D.M. Ritchie .. class:: compact - hello world actually the above example is typeset as .. class:: revlog Revision history ================ :Revision: 1.2 (2012-11-20) :Author: K.V. Smelkov - edit1 - edit2 - edit3 :Revision: 1.1. (2003-04-25) :Author: S.V. Satsky - navy start :Revision: 1.0 (1970-01-01) :Author: B.W. Kernighan, D.M. Ritchie - hello world and custom transform adds revloghead and compact classes for items in sections of class revlog:: class RevLogTransform(Transform): """Пост-обработка разделов с историей изменений Выставляет classes для элементов внутри раздела помеченного как revlog например .. class:: revlog История изменений ----------------- :Редакция: 123 % <- выставит класс revloghead :Автор: Пупкин - сделано то-то и то-то; % <- выставит класс compact - так-то и так-то; Также отделят одну редакцию от другой разделителем. """ default_priority = 850 # XXX ok? def apply(self): for section in self.document.traverse(nodes.section): if not 'revlog' in section['classes']: continue firsthead = True i=0 while i<len(section.children): node = section.children[i] if isinstance(node, nodes.bullet_list): if not node['classes']: node['classes'] += ['compact'] elif isinstance(node, nodes.field_list): if not node['classes']: node['classes'] += ['revloghead'] if 'revloghead' in node['classes']: if firsthead: firsthead = False else: revtransition = latex(r'\bigskip\hrule\bigskip') # XXX section.insert(i, revtransition) i += 1 i += 1 Style for revloghead fieldlists: \newenvironment{DUfieldlistrevloghead}{% \begingroup% \renewcommand{\item}[1][]{% \item[##1]% \ifthenelse{\equal{##1}{Revision:}}{\bf}{\rm}% }% \begin{list}{}{% \itemsep=0pt\parsep=0pt% чтобы строчки шли одна за другой без лишнего vspace % http://www.latex-community.org/forum/viewtopic.php?f=5&t=7607 \renewcommand{\makelabel}[1]{\rm ##1\hfill} \settowidth\labelwidth{\makelabel{Revision: \quad}}% %\setlength\labelwidth{65pt}% \setlength\leftmargin{\labelwidth}% \addtolength\labelwidth{-\labelsep}% % }% }{% \end{list}% \endgroup% } (again this is probably ugly, provided only as example) ~~~~ Sorry, this mail was written in a hurry... Thanks, Kirill |