prepared to be told i'm an idiot but for the purposes of cleaning up
some of the error messages from "make htmldocs", i wanted to not only
delete some diagnostic-generating lines, but comment out others and,
apparently, commenting out lines in a .tmpl file is not as easy as i
thought.
if i do a regular build and look at, say, alsa-driver-api.tmpl,
there's a snippet of kernel-doc directives:
... snip ...
<sect1><title>ASoC Core API</title>
!Iinclude/sound/soc.h
!Esound/soc/soc-core.c
!Esound/soc/soc-cache.c
!Esound/soc/soc-devres.c
!Esound/soc/soc-io.c
!Esound/soc/soc-pcm.c
</sect1>
... snip ...
and if i pick on, say, the line for soc-core.c, i can see the
corresponding output in the XML file:
... snip ...
<!-- sound/soc/soc-core.c -->
<refentry id="API-snd-soc-runtime-set-dai-fmt">
<refentryinfo>
<title>LINUX</title>
... snip ...
where the XML generated for that directive helpfully(?) starts with a
comment containing the filename.
however, let's say i wanted to not include that content in my final
manual but, rather than delete the line, i want to comment it out to
leave a reminder to myself to do something with it later. so i
unthinkingly do this:
<!-- need to fix this later, don't forget: rday
!Esound/soc/soc-core.c
-->
apparently, that explodes as the generated XML looks like this:
.... snip ...
<!-- need to fix this later, don't forget: rday
<!-- sound/soc/soc-core.c -->
<refentry id="API-snd-soc-runtime-set-dai-fmt">
<refentryinfo>
<title>LINUX</title>
... snip ...
and i understandably get an error about a double hyphen within a
comment and parsing fails.
i can see from gadget.tmpl how one might comment out a single
directive -- by commenting on the same physical line:
<!-- !Edrivers/usb/gadget/net2280.c -->
but what if i wanted to comment out, say, a section from a .tmpl file
that contains numerous kernel-doc directives? is there an elegant way
to do that, short of having to comment out every single line?
rday
--
========================================================================
Robert P. J. Day Ottawa, Ontario, CANADA
http://crashcourse.ca
Twitter: http://twitter.com/rpjday
LinkedIn: http://ca.linkedin.com/in/rpjday
========================================================================
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majordomo@xxxxxxxxxxxxxxx
More majordomo info at http://vger.kernel.org/majordomo-info.html
