Two more man page errors (maybe)

Two more man page errors (maybe)

[Jeremy Nicoll - ml sox users]

I'm very new to sox so I might have got this wrong.  I read through the 
PDF version
of the sox manual (for v14-4-2) and was puzzled by several things:

a) why (at 84 pages long) does it seem to be a 42-page document, twice?


b) on page 12, discussing the '--channels' effect, it says:

        For an output file, this option provides a shorthand for
        specifying that the channels effect should be invoked in
        order to change (if necessary) the number of channels in
        the audio signal to the number given. For example, the
        following two commands are equivalent:

         sox input.wav -c 1 output.wav bass -b 24
         sox input.wav output.wav bass -b 24 channels 1

        though the second form is more flexible as it allows the
        effects to be ordered arbitrarily.


    But both commands look wrong to me; how can "-b 24" follow the
    'bass' effect name?   I thought that "-b 24" was a file option
    which should be before the output file's name?

    Likewise on p13, in text about '--rate':

        For an output file, this option provides a shorthand for
        specifying that the rate effect should be invoked in order
        to change (if necessary) the sample rate of the audio signal
        to the given value.  For example, the following two commands
        are equivalent:

           sox input.wav -r 48k output.wav bass -b 24
           sox input.wav output.wav bass -b 24 rate 48k



c) On page 15 in "Multiple Effects Chains" it says:

        The following is an example of multiple effects chains. It
        will split the input file into multiple files of 30 seconds
        in length. Each output filename will have unique number in
        its name as documented in the Output Files section.

           sox infile.wav output.wav trim 0 30 : newfile : restart

    But doesn't the command have to use the %n format in the output
    file name for numbered output files to work?



-- 
Jeremy Nicoll - my opinions are my own

------------------------------------------------------------------------------
Site24x7 APM Insight: Get Deep Visibility into Application Performance
APM + Mobile APM + RUM: Monitor 3 App instances at just $35/Month
Monitor end-to-end web transactions and take corrective actions now
Troubleshoot faster and improve end-user experience. Signup Now!
http://pubads.g.doubleclick.net/gampad/clk?id=267308311&iu=/4140

Re: Two more man page errors (maybe)

[Kevin Conder]

[-- Attachment #1.1: Type: text/plain, Size: 818 bytes --]

On Sat, Jan. 23rd, Jeremy Nicoll wrote:

> I'm very new to sox so I might have got this wrong.  I read through the
> PDF version
> of the sox manual (for v14-4-2) and was puzzled by several things:
>
> a) why (at 84 pages long) does it seem to be a 42-page document, twice?

I played around with pdfroff, the program that makes the PDF files. It
looks like pdfroff creates the duplicate pages when it makes the table of
contents, which isn't needed. I found eliminating the table of contents
step fixes the problem.

I propose adding the "--no-toc-relocation" parameter to the pdfroff lines
in the Makefile from this:

pdfroff -t -man -Tps $(srcdir)/$< > $@

To this:

pdfroff -t --no-toc-relocation -man -Tps $(srcdir)/$< > $@

Should I post this to the dev mailing list or generate a pull request?

-- 
Kevin Conder

[-- Attachment #1.2: Type: text/html, Size: 1032 bytes --]

[-- Attachment #2: Type: text/plain, Size: 413 bytes --]

------------------------------------------------------------------------------
Site24x7 APM Insight: Get Deep Visibility into Application Performance
APM + Mobile APM + RUM: Monitor 3 App instances at just $35/Month
Monitor end-to-end web transactions and take corrective actions now
Troubleshoot faster and improve end-user experience. Signup Now!
http://pubads.g.doubleclick.net/gampad/clk?id=267308311&iu=/4140

[-- Attachment #3: Type: text/plain, Size: 158 bytes --]

_______________________________________________
Sox-users mailing list
Sox-users@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/sox-users

Re: Two more man page errors (maybe)

[Jan Stary]

On Jan 23 12:00:52, jn.ml.sxu.88@wingsandbeaks.org.uk wrote:
> I'm very new to sox so I might have got this wrong.  I read through the 
> PDF version
> of the sox manual (for v14-4-2) and was puzzled by several things:
> 
> a) why (at 84 pages long) does it seem to be a 42-page document, twice?

This seems to be the case for all of them:

http://sox.sourceforge.net/sox.pdf
http://sox.sourceforge.net/soxi.pdf
http://sox.sourceforge.net/soxformat.pdf
http://sox.sourceforge.net/libsox.pdf

Apparently, the way PDFs are cretaed from the man(7) source is broken,
but nobody reads the PDFs anyway :-)

> b) on page 12, discussing the '--channels' effect, it says:
> 
>         For an output file, this option provides a shorthand for
>         specifying that the channels effect should be invoked in
>         order to change (if necessary) the number of channels in
>         the audio signal to the number given. For example, the
>         following two commands are equivalent:
> 
>          sox input.wav -c 1 output.wav bass -b 24
>          sox input.wav output.wav bass -b 24 channels 1
> 
>         though the second form is more flexible as it allows the
>         effects to be ordered arbitrarily.
> 
> 
>     But both commands look wrong to me; how can "-b 24" follow the
>     'bass' effect name?   I thought that "-b 24" was a file option
>     which should be before the output file's name?

You are right: the bass effect takes a 'gain' argument,
and '-b 24' is not a gain argument. Similarly in the other one.


>     Likewise on p13, in text about '--rate':
> 
>         For an output file, this option provides a shorthand for
>         specifying that the rate effect should be invoked in order
>         to change (if necessary) the sample rate of the audio signal
>         to the given value.  For example, the following two commands
>         are equivalent:
> 
>            sox input.wav -r 48k output.wav bass -b 24
>            sox input.wav output.wav bass -b 24 rate 48k

Yes, same thing.

If I had time, I would reread the whole manpage, an if I really had time,
I would rewrite it into mdoc(7) and switch the doc build system to mandoc
( http://mdocml.bsd.lv/ ). But I don't have the time.


> c) On page 15 in "Multiple Effects Chains" it says:
> 
>         The following is an example of multiple effects chains. It
>         will split the input file into multiple files of 30 seconds
>         in length. Each output filename will have unique number in
>         its name as documented in the Output Files section.
> 
>            sox infile.wav output.wav trim 0 30 : newfile : restart
> 
>     But doesn't the command have to use the %n format in the output
>     file name for numbered output files to work?

Just run it:

  $ sox -n infile.wav trim 0 00:05:00 
  $ sox infile.wav output.wav trim 0 30 : newfile : restart
  $ ls -l output*

To quote the manpage:

  In multiple output mode, a unique number will automatically
  be appended to the end of all filenames.  If the filename
  has an extension then the number is inserted before the
  extension.  This behaviour can be customized by placing a
  %n anywhere in the filename where the number should be
  substituted.  An optional number can be placed after the %
  to indicate a minimum fixed width for the number.
  

	Jan


------------------------------------------------------------------------------
Site24x7 APM Insight: Get Deep Visibility into Application Performance
APM + Mobile APM + RUM: Monitor 3 App instances at just $35/Month
Monitor end-to-end web transactions and take corrective actions now
Troubleshoot faster and improve end-user experience. Signup Now!
http://pubads.g.doubleclick.net/gampad/clk?id=267308311&iu=/4140

Re: Two more man page errors (maybe)

[Jeremy Nicoll - ml sox users]

On 2016-01-26 06:50, Jan Stary wrote:

> Apparently, the way PDFs are cretaed from the man(7) source is broken,
> but nobody reads the PDFs anyway :-)

I know it was a joke, but I should think pretty much every non-linux 
user
does read the PDFs; no easy way to read man pages on Windows...


>>     But both commands look wrong to me; how can "-b 24" follow the
>>     'bass' effect name?   I thought that "-b 24" was a file option
>>     which should be before the output file's name?
> 
> You are right: the bass effect takes a 'gain' argument,
> and '-b 24' is not a gain argument. Similarly in the other one.



>>     But doesn't the command have to use the %n format in the output
>>     file name for numbered output files to work?
> 
> Just run it:
> 
>   $ sox -n infile.wav trim 0 00:05:00
>   $ sox infile.wav output.wav trim 0 30 : newfile : restart
>   $ ls -l output*
> 
> To quote the manpage:
> 
>   In multiple output mode, a unique number will automatically
>   be appended to the end of all filenames.

Oops.  I'm sure I read that at some point but what had stuck in my
mind was the example of %n usage.

-- 
Jeremy Nicoll - my opinions are my own

------------------------------------------------------------------------------
Site24x7 APM Insight: Get Deep Visibility into Application Performance
APM + Mobile APM + RUM: Monitor 3 App instances at just $35/Month
Monitor end-to-end web transactions and take corrective actions now
Troubleshoot faster and improve end-user experience. Signup Now!
http://pubads.g.doubleclick.net/gampad/clk?id=267308311&iu=/4140

Re: Two more man page errors (maybe)

[Peter Shute]

> > Apparently, the way PDFs are cretaed from the man(7) source is broken,
> > but nobody reads the PDFs anyway :-)
> 
> I know it was a joke, but I should think pretty much every non-linux user
> does read the PDFs; no easy way to read man pages on Windows...

Acrobat has better search tools, so I sometimes read the pdfs. It's always annoyed me that you can't copy and paste the examples from the pdfs to a command line - the minus symbols are in the pdf as a Unicode character, not plain ASCII. Nor can you search for an option by its code for the same reason.

Peter Shute

------------------------------------------------------------------------------
Site24x7 APM Insight: Get Deep Visibility into Application Performance
APM + Mobile APM + RUM: Monitor 3 App instances at just $35/Month
Monitor end-to-end web transactions and take corrective actions now
Troubleshoot faster and improve end-user experience. Signup Now!
http://pubads.g.doubleclick.net/gampad/clk?id=267308311&iu=/4140