[FFmpeg-cvslog] doc: reorganize developer.texi chapter hierarchy

Sun Dec 3 07:09:08 EET 2017

ffmpeg | branch: master | Jim DeLaHunt <from.ffmpeg-dev at jdlh.com> | Sun Nov 26 00:31:11 2017 -0800| [42a22d01d1a0d49b83121228df816d8183f0b85c] | committer: Timothy Gu

doc: reorganize developer.texi chapter hierarchy

Previously, the Developer Documentation <ffmpeg.org/developer.html>
contained a single chapter, "1. Developer Guide," with all content under
that single chapter. Thus the document structure was one level deeper
and more complicated than it needed to be.  It differed from similar
documents such as /faq.html, which have multiple chapters.

Eliminate the single chapter, and promote each section underneath to
chapter, and each subsection to section. Thus content and relative
structure remains the same, but the overall structure is simpler.
Anchors within the page remain the same.

Signed-off-by: Jim DeLaHunt <from.ffmpeg-dev at jdlh.com>
Signed-off-by: Timothy Gu <timothygu99 at gmail.com>

> http://git.videolan.org/gitweb.cgi/ffmpeg.git/?a=commit;h=42a22d01d1a0d49b83121228df816d8183f0b85c
---

 doc/developer.texi | 53 ++++++++++++++++++++++++++---------------------------
 1 file changed, 26 insertions(+), 27 deletions(-)

diff --git a/doc/developer.texi b/doc/developer.texi
index a7b4f1d737..89124a295c 100644
--- a/doc/developer.texi
+++ b/doc/developer.texi
@@ -10,9 +10,7 @@
 
 @contents
 
- at chapter Developers Guide
-
- at section Notes for external developers
+ at chapter Notes for external developers
 
 This document is mostly useful for internal FFmpeg developers.
 External developers who need to use the API in their application should
@@ -30,7 +28,7 @@ For more detailed legal information about the use of FFmpeg in
 external programs read the @file{LICENSE} file in the source tree and
 consult @url{https://ffmpeg.org/legal.html}.
 
- at section Contributing
+ at chapter Contributing
 
 There are 3 ways by which code gets into FFmpeg.
 @itemize @bullet
@@ -47,9 +45,9 @@ The developer making the commit and the author are responsible for their changes
 and should try to fix issues their commit causes.
 
 @anchor{Coding Rules}
- at section Coding Rules
+ at chapter Coding Rules
 
- at subsection Code formatting conventions
+ at section Code formatting conventions
 
 There are the following guidelines regarding the indentation in files:
 
@@ -74,7 +72,7 @@ The presentation is one inspired by 'indent -i4 -kr -nut'.
 The main priority in FFmpeg is simplicity and small code size in order to
 minimize the bug count.
 
- at subsection Comments
+ at section Comments
 Use the JavaDoc/Doxygen  format (see examples below) so that code documentation
 can be generated automatically. All nontrivial functions should have a comment
 above them explaining what the function does, even if it is just one sentence.
@@ -114,7 +112,7 @@ int myfunc(int my_parameter)
 ...
 @end example
 
- at subsection C language features
+ at section C language features
 
 FFmpeg is programmed in the ISO C90 language with a few additional
 features from ISO C99, namely:
@@ -160,7 +158,7 @@ mixing statements and declarations;
 GCC statement expressions (@samp{(x = (@{ int y = 4; y; @})}).
 @end itemize
 
- at subsection Naming conventions
+ at section Naming conventions
 All names should be composed with underscores (_), not CamelCase. For example,
 @samp{avfilter_get_video_buffer} is an acceptable function name and
 @samp{AVFilterGetVideo} is not. The exception from this are type names, like
@@ -204,7 +202,7 @@ letter as they are reserved by the C standard. Names starting with @code{_}
 are reserved at the file level and may not be used for externally visible
 symbols. If in doubt, just avoid names starting with @code{_} altogether.
 
- at subsection Miscellaneous conventions
+ at section Miscellaneous conventions
 
 @itemize @bullet
 @item
@@ -216,7 +214,7 @@ Casts should be used only when necessary. Unneeded parentheses
 should also be avoided if they don't make the code easier to understand.
 @end itemize
 
- at subsection Editor configuration
+ at section Editor configuration
 In order to configure Vim to follow FFmpeg formatting conventions, paste
 the following snippet into your @file{.vimrc}:
 @example
@@ -249,9 +247,9 @@ For Emacs, add these roughly equivalent lines to your @file{.emacs.d/init.el}:
 (setq c-default-style "ffmpeg")
 @end lisp
 
- at section Development Policy
+ at chapter Development Policy
 
- at subsection Patches/Committing
+ at section Patches/Committing
 @subheading Licenses for patches must be compatible with FFmpeg.
 Contributions should be licensed under the
 @uref{http://www.gnu.org/licenses/lgpl-2.1.html, LGPL 2.1},
@@ -350,7 +348,7 @@ time-frame (12h for build failures and security fixes, 3 days small changes,
 1 week for big patches) then commit your patch if you think it is OK.
 Also note, the maintainer can simply ask for more time to review!
 
- at subsection Code
+ at section Code
 @subheading API/ABI changes should be discussed before they are made.
 Do not change behavior of the programs (renaming options etc) or public
 API or ABI without first discussing it on the ffmpeg-devel mailing list.
@@ -381,7 +379,8 @@ Never write to unallocated memory, never write over the end of arrays,
 always check values read from some untrusted source before using them
 as array index or other risky things.
 
- at subsection Documentation/Other
+ at section 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
@@ -406,7 +405,7 @@ finding a new maintainer and also don't forget to update the @file{MAINTAINERS}
 
 We think our rules are not too hard. If you have comments, contact us.
 
- at section Code of conduct
+ at chapter Code of conduct
 
 Be friendly and respectful towards others and third parties.
 Treat others the way you yourself want to be treated.
@@ -436,7 +435,7 @@ Finally, keep in mind the immortal words of Bill and Ted,
 "Be excellent to each other."
 
 @anchor{Submitting patches}
- at section Submitting patches
+ at chapter Submitting patches
 
 First, read the @ref{Coding Rules} above if you did not yet, in particular
 the rules regarding patch submission.
@@ -485,7 +484,7 @@ Give us a few days to react. But if some time passes without reaction,
 send a reminder by email. Your patch should eventually be dealt with.
 
 
- at section New codecs or formats checklist
+ at chapter New codecs or formats checklist
 
 @enumerate
 @item
@@ -537,7 +536,7 @@ Did you make sure it compiles standalone, i.e. with
 @end enumerate
 
 
- at section patch submission checklist
+ at chapter Patch submission checklist
 
 @enumerate
 @item
@@ -650,7 +649,7 @@ Test your code with valgrind and or Address Sanitizer to ensure it's free
 of leaks, out of array accesses, etc.
 @end enumerate
 
- at section Patch review process
+ at chapter Patch review process
 
 All patches posted to ffmpeg-devel will be reviewed, unless they contain a
 clear note that the patch is not for the git master branch.
@@ -681,7 +680,7 @@ to be reviewed, please consider helping to review other patches, that is a great
 way to get everyone's patches reviewed sooner.
 
 @anchor{Regression tests}
- at section Regression tests
+ at chapter Regression tests
 
 Before submitting a patch (or committing to the repository), you should at least
 test that you did not break anything.
@@ -692,7 +691,7 @@ Running 'make fate' accomplishes this, please see @url{fate.html} for details.
 this case, the reference results of the regression tests shall be modified
 accordingly].
 
- at subsection Adding files to the fate-suite dataset
+ at section Adding files to the fate-suite dataset
 
 When there is no muxer or encoder available to generate test media for a
 specific test then the media has to be included in the fate-suite.
@@ -703,7 +702,7 @@ Once you have a working fate test and fate sample, provide in the commit
 message or introductory message for the patch series that you post to
 the ffmpeg-devel mailing list, a direct link to download the sample media.
 
- at subsection Visualizing Test Coverage
+ at section Visualizing Test Coverage
 
 The FFmpeg build system allows visualizing the test coverage in an easy
 manner with the coverage tools @code{gcov}/@code{lcov}.  This involves
@@ -730,7 +729,7 @@ You can use the command @code{make lcov-reset} to reset the coverage
 measurements. You will need to rerun @code{make lcov} after running a
 new test.
 
- at subsection Using Valgrind
+ at section Using Valgrind
 
 The configure script provides a shortcut for using valgrind to spot bugs
 related to memory handling. Just add the option
@@ -744,7 +743,7 @@ In case you need finer control over how valgrind is invoked, use the
 your configure line instead.
 
 @anchor{Release process}
- at section Release process
+ at chapter Release process
 
 FFmpeg maintains a set of @strong{release branches}, which are the
 recommended deliverable for system integrators and distributors (such as
@@ -776,7 +775,7 @@ adjustments to the symbol versioning file. Please discuss such changes
 on the @strong{ffmpeg-devel} mailing list in time to allow forward planning.
 
 @anchor{Criteria for Point Releases}
- at subsection Criteria for Point Releases
+ at section Criteria for Point Releases
 
 Changes that match the following criteria are valid candidates for
 inclusion into a point release:
@@ -800,7 +799,7 @@ point releases of the same release branch.
 The order for checking the rules is (1 OR 2 OR 3) AND 4.
 
 
- at subsection Release Checklist
+ at section Release Checklist
 
 The release process involves the following steps:
 

