[FFmpeg-devel] How to preserve @subheading directives, and styling, when compiling doc/developer.texi ?

[Jim DeLaHunt]

On 2017-11-21 01:20, Jim DeLaHunt wrote:

> Hello, doc maintainers:
>
> Could I get some help with the Texinfo compilation which produces 
> /developer.html, please?
>
> Page <http://ffmpeg.org/developer.html> is a document which has some 
> section headings displayed in green text, and some subheadings 
> displayed in grey text. Section headings appear in the Table of 
> Contents, but subheadings do not. For instance, at 
> <http://ffmpeg.org/developer.html#Documentation_002fOther>, the 
> section begins:
>
> ------------------------------------------------------------------------
>
>
>        _1.4.3 Documentation/Other_
>
>
>        _Subscribe to the ffmpeg-cvslog mailing list._
>
> __
>
> It is important to do this as the diffs of all commits are sent there 
> and reviewed by all the other developers. Bugs and possible 
> improvements or general questions regarding commits are discussed 
> there. We expect you to react if problems with your code are uncovered.
>
> ------------------------------------------------------------------------
>
> I believe this page corresponds to file /doc/developer.html in the 
> FFmpeg build tree, which is compiled from source in 
> /doc/developer.texi via "make doc".
>
> When I do "make doc" and generate /doc/developer.html from the current 
> *master* branch (commit ba98f84), I get a different-looking HTML file. 
> The section title is in light grey text, and the subheading is missing 
> entirely.  At 
> <file:///Users/myuser/workspace/ffmpeg/doc/developer.html#Documentation_002fOther>, 
> the section begins:
>
> ------------------------------------------------------------------------
>
>
>        _1.4.3 Documentation/Other_
>
> It is important to do this as the diffs of all commits are sent there 
> and reviewed by all the other developers. Bugs and possible 
> improvements or general questions regarding commits are discussed 
> there. We expect you to react if problems with your code are uncovered.
> ------------------------------------------------------------------------
>
> The section headings come from @section and @subsection directives. 
> The subheadings come from @subheading directives. In 
> doc/developer.texi, the source of this section reads,
>
> ------------------------------------------------------------------------
> @subsection Documentation/Other
> @subheading Subscribe to the ffmpeg-cvslog mailing list.
> It is important to do this as the diffs of all commits are sent there and
> reviewed by all the other developers. Bugs and possible improvements or
> general questions regarding commits are discussed there. We expect you to
> react if problems with your code are uncovered.
> ------------------------------------------------------------------------
>
> So, it appears that when compiling on my local machine, the 
> @subheading directives are discarded, and the styling differs from 
> what is on ffmpeg.org.
>
> How can I compile /doc/developer.html from the FFmpeg sources so that:
>
> 1. the subheadings are included, and
>
> 2. the styling matches what is at ffmpeg.org/developer.html
>
> Thanks in advance for your help.  Best regards,
>        —Jim DeLaHunt

Hearing no suggestions, I've filed a bug report:

*HTML generation differences (@subheading missing, formatting) in local 
build compared to official build* (#6872) 
<https://trac.ffmpeg.org/ticket/6872#ticket>

So, hopefully the issue will be tracked and investigated in due course.

Best regards,
       —Jim DeLaHunt


-- 
     --Jim DeLaHunt, jdlh at jdlh.com     http://blog.jdlh.com/ (http://jdlh.com/)
       multilingual websites consultant

       355-1027 Davie St, Vancouver BC V6E 4L2, Canada
          Canada mobile +1-604-376-8953