Re: sidebar in docbook

[Patrice Dumas]

On Fri, Apr 05, 2013 at 12:10:46AM +0000, Karl Berry wrote:
> Hi Patrice (et al.),
> 
> Arnold proposed an @sidebar environment in Texinfo, primarily so that he
> can get <sidebar><title>Some Title</title>blah blah</sidebar> in Docbook.
> 
> For other output formats, he proposed that the output would be like this:
> 
>     @cartouche
>     @center @b{Some Title}
>     blah blah
>     @end cartouche
> 
> Sadly, I have to say I don't like it.  My problem is simply that
> @cartouche @center is not what people actually expect to see as a
> "sidebar", so it seems rather a lie; it would be hard to document
> coherently and truthfully.  And I can't see a feasible/desirable way to
> implement a real sidebar in HTML or Info or TeX.

I don't know what people expect, but I just checked that the formatting
of <sidebar> with docbook2html or docbook2pdf is not something
complicated, but very like the snippet above, without the @center, more
like
 
   @cartouche
   @b{Some Title}

   blah blah
   @end cartouche


> Nevertheless, even if sidebars can't be implemented in general, it seems
> like it should be possible in our brave new world for Arnold to do some
> combination of Texinfo and Perl such that he gets his sidebars in a
> reasonable way.  I admit I am rather at a loss for a real suggestion,
> though.
> 
> Wdyt?

I don't think perl hackery is needed, a simple macro would do, like

@macro @sidebar{title, content}
@ifdocbook
@inlinefmt{docbook, <sidebar><title>}
\title\
@inlinefmt{docbook, </title>}
\content\
@inlinefmt{docbook, </sidebar>}
@end ifdocbook
@ifnotdocbook
@cartouche
@b{\title\}

\content\
@end cartouche
@end ifnotdocbook
@end macro

In case the content is very long and breaks TeX when passed as a user
defined macro argument, it could also be possible to define a pseudo
environment with @end, like

@macro @begin-sidebar{title}
@ifdocbook
@inlinefmt{docbook, <sidebar><title>}
\title\
@inlinefmt{docbook, </title>}
@end ifdocbook
@ifnotdocbook
@cartouche
@b{\title\}


@end ifnotdocbook
@end macro

@macro @end-sidebar{}
@ifdocbook
@inlinefmt{docbook, </sidebar>}
@end ifdocbook
@ifnotdocbook
@end cartouche
@end ifnotdocbook
@end macro


I haven't tested, so maybe I missed a new line somewhere.
Such macros could be problematic with TeX, as usual, but this is
the best option to me.  To be backward compatible, instead of 
@inlinefmt, @docbook/@end docbook should be used.

-- 
Pat