[FFmpeg-devel] [PATCH 1/2] doc: do not generate doc/avoptions_(codecs|formats).texi

Thu Oct 10 16:20:09 CEST 2013

On Wed, Oct 09, 2013 at 07:46:15PM -0700, Timothy Gu wrote:
> On Mon, Sep 16, 2013 at 5:19 AM, Michael Niedermayer <michaelni at gmx.at> wrote:
> > On Mon, Sep 16, 2013 at 02:05:22PM +0200, Michael Niedermayer wrote:
> >> On Sun, Sep 15, 2013 at 07:27:55PM -0700, Timothy Gu wrote:
> >> > On Sep 15, 2013 1:31 PM, "Michael Niedermayer" <michaelni at gmx.at> wrote:
> >> > >
> >> > > On Sun, Sep 15, 2013 at 08:59:19AM -0700, Timothy Gu wrote:
> >> > > > On Sep 15, 2013 4:35 AM, "Michael Niedermayer" <michaelni at gmx.at> wrote:
> >> > > > >
> >> > > > > On Sun, Sep 15, 2013 at 11:51:37AM +0200, Stefano Sabatini wrote:
> >> > > > > > On date Tuesday 2013-09-10 18:52:54 +0200, Michael Niedermayer
> >> > encoded:
> >> > > > > > > On Mon, Sep 09, 2013 at 09:56:08AM +0200, Stefano Sabatini wrote:
> >> > > > > > [...]
> >> > > > > > > > > diff --git a/.gitignore b/.gitignore
> >> > > > > > > > > index 1f13ec4..807ecb1 100644
> >> > > > > > > > > --- a/.gitignore
> >> > > > > > > > > +++ b/.gitignore
> >> > > > > > > > > @@ -33,8 +33,6 @@
> >> > > > > > > > >  /doc/*.html
> >> > > > > > > > >  /doc/*.pod
> >> > > > > > > > >  /doc/config.texi
> >> > > > > > > > > -/doc/avoptions_codec.texi
> >> > > > > > > > > -/doc/avoptions_format.texi
> >> > > > > > > > >  /doc/examples/decoding_encoding
> >> > > > > > > > >  /doc/examples/demuxing
> >> > > > > > > > >  /doc/examples/filtering_audio
> >> > > > > > > > > diff --git a/doc/Makefile b/doc/Makefile
> >> > > > > > > > > index 7415899..cfd2ca5 100644
> >> > > > > > > > > --- a/doc/Makefile
> >> > > > > > > > > +++ b/doc/Makefile
> >> > > > > > > > > @@ -50,13 +50,6 @@ doc/%.txt: doc/%.texi
> >> > > > > > > > >         $(Q)$(TEXIDEP)
> >> > > > > > > > >         $(M)makeinfo --force --no-headers -o $@ $< 2>/dev/null
> >> > > > > > > > >
> >> > > > > > > > > -GENTEXI  = format codec
> >> > > > > > > > > -GENTEXI := $(GENTEXI:%=doc/avoptions_%.texi)
> >> > > > > > > > > -
> >> > > > > > > > > -$(GENTEXI): TAG = GENTEXI
> >> > > > > > > > > -$(GENTEXI): doc/avoptions_%.texi:
> >> > doc/print_options$(HOSTEXESUF)
> >> > > > > > > > > -       $(M)doc/print_options $* > $@
> >> > > > > > > > > -
> >> > > > > > > > >  doc/%.html: TAG = HTML
> >> > > > > > > > >  doc/%.html: doc/%.texi $(SRC_PATH)/doc/t2h.init $(GENTEXI)
> >> > > > > > > > >         $(Q)$(TEXIDEP)
> >> > > > > > > >
> >> > > > > > > > I suppose it's OK. I suggest to keep the generating program for
> >> > > > > > > > easing merges.
> >> > > > > > >
> >> > > > > > > if the programs are kept, code to build and test them should be
> >> > kept
> >> > > > > > > too.
> >> > > > > >
> >> > > > >
> >> > > > > > > Also are our handwritten files complete and uptodate compared to
> >> > the
> >> > > > > > > autobuild ones ?
> >> > > > > >
> >> > > > > > We do an effort to keep them updated, but of course there is no
> >> > > > > > automated way to keep them updated/synched with the descriptions
> >> > > > > > (that's why we should add documentation when adding options).
> >> > > > >
> >> > > > > I belive that who objects to the automated system has to do the work
> >> > > > > that not using it causes.
> >> > > >
> >> > > > ...which is not me. When i submit the patch, the two files are already
> >> > > > useless. So it is the person who first created the codecs.texi file.
> >> > > >
> >> > > > >
> >> > > > > In practice id say
> >> > > > > That involves at least keeping track of changes of the automated
> >> > > > > output and integrating them. That way its also always known if or what
> >> > > > > is missing.
> >> > > >
> >> > > > +1
> >> > > > However, it is easy for changes from us, hard for changes from fork, as
> >> > > > they are the ones using the util.
> >> > >
> >> > > it should not be hard
> >> > > 1. run the tool with the last checkout of ffmpeg with which things
> >> > >    where in sync
> >> > > 2. run the tool with HEAD of ffmpeg
> >> > >
> >> > > 3. diff the resulting files
> >> > > 4. integrate the changes into the docs
> >> > >
> >> > > in above it makes no difference from where the changes originate
> >> >
> >> > I know. But who's going to do that? You? But definitely not me (I just
> >> > started high school and there's an inf amount of homework).
> >>
> >> Like i said, thouse who pushed for the change should do the work.
> >> That wasnt me, not that i consider a well maintaned manually written
> >> text a bad idea, but i just knew i would not have the motivation to
> >> maintain it.
> >> Alternatively maybe someone else volunteers to maintain these docs?
> >
> > also i suspect people overestimate the amount of work for that.
> > Once automated and manual are in "sync" changes probably would be a
> > matter of copy and pasting a few lines from the automated scrpts output
> > diff to the docs each week ...
> 
> It isn't much work, but see commits abf2d53d and 547c2f00, why don't
> *you* practice what you said?
> 
> New patch attached. I kept the rules for generating them for future convenience.
> 
> Timothy

>  Makefile |   12 ++++++------
>  1 file changed, 6 insertions(+), 6 deletions(-)
> 41565b840d93d3dd2ae84d2afb0ee869e4eb6c5a  0001-doc-do-not-auto-generate-doc-avoptions_-codecs-forma.patch
> From fc70c147a5a2149df90b9a4162600317b8b73015 Mon Sep 17 00:00:00 2001
> From: Timothy Gu <timothygu99 at gmail.com>
> Date: Mon, 23 Sep 2013 19:20:14 -0700
> Subject: [PATCH 1/3] doc: do not auto-generate
>  doc/avoptions_(codecs|formats).texi
> 
> The contents of the two files have been hardcoded to codecs.texi and
> formats.texi, so there is no use for generating the two files during build
> time.
> 
> I kept the rules for generating them for future convenience.

its probably best when they also still get build with a plain "make"
this ensures they are tested and work, otherwise it could easily
be that they stop compiling or working with the developer breaking
them not noticing

[...]

-- 
Michael     GnuPG fingerprint: 9FF2128B147EF6730BADF133611EC787040B0FAB

There will always be a question for which you do not know the correct answer.
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 198 bytes
Desc: Digital signature
URL: <http://ffmpeg.org/pipermail/ffmpeg-devel/attachments/20131010/f2332bdf/attachment.asc>