Re: [PATCH v2 9/9] docs: staging: use small font for literal includes

[Mauro Carvalho Chehab]

Em Tue, 23 Jun 2020 16:12:04 -0700
Joe Perches <joe@xxxxxxxxxxx> escreveu:

> On Tue, 2020-06-23 at 11:53 +0200, Mauro Carvalho Chehab wrote:
> > The normal font is too big to display 80 columns, causing extra
> > breaks to be added at weird places.
> > 
> > change to the footnotesize, as this would fit a little bit
> > better.  
> []
> > diff --git a/Documentation/staging/index.rst b/Documentation/staging/index.rst  
> []
> > @@ -19,14 +19,41 @@ Unsorted Documentation
> >  Atomic Types
> >  ============
> >  
> > -.. literalinclude:: ../atomic_t.txt
> > +.. raw:: latex
> > +
> > +    \footnotesize
> > +
> > +.. include:: ../atomic_t.txt
> > +   :literal:
> > +
> > +.. raw:: latex
> > +
> > +    \normalsize  
> 
> Is there something like push/pop for styles?
> Maybe some variant of include:: with a style?

Well, one could use, instead:

	.. css-class:: some_footnote_class 

Which should then require a "some_footnote_class" css file defined for
html output and a set of macros to be added at the "latex_elements"
section of conf.py. 

If properly defined, I guess it should be possible to avoid the need
of returning to the normal size after using it.

This is easily said than done.

One of the problems with using such macros is that the macro
should be prepared to work not only with plain text but also with
more complex structures like tables or graphics.

We do need to use tricks like changing the font size on media docs,
in order to display tables with long lines. We have several of them
there, with bit mappings.

I tried a few times to play with that for PDF. I ended needing to 
revert all such attempts[1]. The main problem playing with those is that
You'll end needing to play with the already defined macros found on
sphinx.sty, which is shipped together with Sphinx. The macros there
changed a lot over the time. Making something that would work with
different versions is really hard. 

[1] I used those when I ported media docs from DocBook, but had to
drop several macros because version 1.7 broke the ones I defined.

On that time, I spent several days writing the first version, and,
when they broke, I spent a long time figuring out what would be the
best.

At the end, using the "raw:: latex" like the above was the only
thing that worked reliable among different Sphinx versions.

Thanks,
Mauro