Enquanto pesquisava outro problema, deparei- me com um comando ,

locate something | xargs -I {} bash -c "if [ -d "{}" ]; then echo {}; fi"

sobre as quais eu queria aprender mais. Então eu corri man xargse recebi a seguinte saída:

XARGS(1)                    General Commands Manual                   XARGS(1)

NAME
       xargs - build and execute command lines from standard input

SYNOPSIS
       xargs  [-0prtx]  [-E  eof-str] [-e[eof-str]] [--eof[=eof-str]] [--null]
       [-d delimiter] [--delimiter delimiter]  [-I  replace-str]  [-i[replace-
       str]]    [--replace[=replace-str]]   [-l[max-lines]]   [-L   max-lines]
       [--max-lines[=max-lines]] [-n max-args] [--max-args=max-args] [-s  max-
       chars]  [--max-chars=max-chars]  [-P max-procs] [--max-procs=max-procs]
       [--interactive]      [--verbose]      [--exit]      [--no-run-if-empty]
       [--arg-file=file]   [--show-limits]   [--version]   [--help]   [command
       [initial-arguments]]

DESCRIPTION
       This manual page documents the GNU version of xargs...

Estou tentando melhorar a documentação para aprender sobre os programas Linux, mas a seção "Sinopse" é intimidadora para novos usuários. Parece literalmente sem sentido em comparação com man locateou man free.

Até agora, entendo que colchetes significam opcionais e colchetes aninhados significam opções em opcional. Mas como devo induzir um comando válido com isso?

Não estou pedindo ajuda com xargs aqui. Estou procurando ajuda para interpretar uma página de manual para entender comandos complicados. Quero deixar de tornar os blogs da Web indexados pelo Google e a ajuda pessoal de outras pessoas a minha primeira abordagem para aprender comandos do Linux.

Bem, esta é minha maneira muito pessoal de ler páginas de manual:

O manpager

Quando você abre uma página de manual usando o mancomando, a saída será exibido / prestados pelos lessou morecomandos, ou qualquer outro comando que será definido como o pager (manpager).

Se você estiver usando Linux, provavelmente será atendido com sua infraestrutura man já configurada para uso /usr/bin/less -is(a menos que você tenha instalado uma distribuição mínima) man(1), como explica na seção Opções:

-P pager
Specify which pager to use. This option overrides the MANPAGER environment variable, 
which in turn overrides the PAGER variable. By default, man uses /usr/bin/less -is.

No FreeBSD e no OpenBSD é apenas uma questão de editar a MANPAGERvariável de ambiente, uma vez que elas serão usadas principalmente more, e alguns recursos, como pesquisa e destaque de texto, podem estar ausentes.

Há uma boa resposta para a pergunta de quais diferenças more, lesse mosttem aqui (nunca usado most). A capacidade de rolar para trás e avançar por página com Spaceou nos dois sentidos por linha com ↓ou ↑(também, usando viligações je k) é essencial durante a navegação nas páginas de manual. Pressione henquanto estiver usando lesspara ver o resumo dos comandos disponíveis.

E é por isso que sugiro que você use lesscomo seu pager manual. lesspossui alguns recursos essenciais que serão usados ​​durante esta resposta.

Como um comando é formatado?

Convenções de utilitários : The Open Group Base Specifications Edição 7 - IEEE Std 1003.1, 2013 Edition. Você deve visitar esse link antes de tentar entender uma página de manual. Esta referência online descreve a sintaxe do argumento dos utilitários padrão e apresenta a terminologia usada em todo o POSIX.1-2017 para descrever os argumentos processados ​​pelos utilitários. Isso também o indiretamente atualizará o significado real de palavras como parâmetros, argumentos, opção de argumento ...

O cabeçalho de qualquer página de manual parecerá menos enigmático para você depois de entender a notação das convenções de utilidade:

utility_name[-a][-b][-c option_argument]
    [-d|-e][-f[option_argument]][operand...]

Tenha em mente o que você quer fazer.

Ao fazer sua pesquisa sobre xargsvocê, fez isso para um investidor, certo? Você tinha uma necessidade específica que estava lendo a saída padrão e executando comandos com base nessa saída.

Mas quando não sei qual comando quero?

Use man -kou apropos(eles são equivalentes). Se eu não sei como encontrar um arquivo: man -k file | grep search. Leia as descrições e encontre uma que melhor atenda às suas necessidades. Exemplo:

apropos -r '^report'
bashbug (1)          - report a bug in bash
df (1)               - report file system disk space usage
e2freefrag (8)       - report free space fragmentation information
filefrag (8)         - report on file fragmentation
iwgetid (8)          - Report ESSID, NWID or AP/Cell Address of wireless network
kbd_mode (1)         - report or set the keyboard mode
lastlog (8)          - reports the most recent login of all users or of a given user
pmap (1)             - report memory map of a process
ps (1)               - report a snapshot of the current processes.
pwdx (1)             - report current working directory of a process
uniq (1)             - report or omit repeated lines
vmstat (8)           - Report virtual memory statistics

Por padrão, o Apropos trabalha com expressões regulares ( man aproposleia a descrição e descubra o que -rfaz). Neste exemplo, estou procurando todas as páginas de manual em que a descrição começa com "report".

Para procurar informações relacionadas à leitura do processamento padrão de entrada / saída e ao alcance xargscomo uma opção possível:

man -k command| grep input
xargs (1)            - build and execute command lines from standard input

Leia sempre o DESCRIPTIONantes de começar

Reserve um tempo e leia a descrição. Apenas lendo a descrição do xargscomando, aprenderemos que:

• xargslê STDIN e executa o comando necessário. Isso também significa que você precisará ter algum conhecimento de como a entrada padrão funciona e como manipulá-la através de pipes para encadear comandos
• O comportamento padrão é agir como /bin/echo. Isso fornece uma pequena dica de que, se você precisar encadear mais de um xargs, não precisará usar eco para imprimir.
• Também aprendemos que os nomes de arquivos unix podem conter linhas em branco e novas linhas, que isso pode ser um problema e o argumento -0é uma maneira de impedir que as coisas explodam usando separadores de caracteres nulos. A descrição avisa que o comando que está sendo usado como entrada também precisa suportar esse recurso e que o GNU o findsuporta. Ótimo. Nós usamos muitas informações com xargs.
• xargs irá parar se o status de saída 255 for alcançado.

Algumas descrições são muito curtas e isso geralmente ocorre porque o software funciona de uma maneira muito simples. Nem pense em pular esta parte da página de manual ;)

Outras coisas para prestar atenção ...

Você sabe que pode procurar arquivos usando find. Há uma tonelada de opções e, se você apenas olhar SYNOPSIS, ficará impressionado com elas. É apenas a ponta do iceberg. Excluindo NAME, SYNOPSISe DESCRIPTION, você terá as seguintes seções:

• AUTHORS: as pessoas que criaram ou ajudaram na criação do comando.

• BUGS: lista todos os defeitos conhecidos. Pode haver apenas limitações de implementação.

• ENVIRONMENT: Aspectos do seu shell que podem ser afetados pelo comando ou variáveis ​​que serão usadas.

• EXAMPLESou NOTES: auto-explicativo.

• REPORTING BUGS: Quem você terá que entrar em contato se encontrar erros nesta ferramenta ou em sua documentação.

• COPYRIGHT: Pessoa que criou e se isenta de responsabilidade do software. Tudo relacionado à licença do próprio software.

• SEE ALSO: Outros comandos, ferramentas ou aspectos de trabalho que estão relacionados a este comando e não cabiam em nenhuma das outras seções.

Você provavelmente encontrará informações interessantes sobre os aspectos que deseja de uma ferramenta na seção de exemplos / notas.

Exemplo

Nas etapas a seguir, tomarei findcomo exemplo, uma vez que seus conceitos são "mais simples" do xargsque explicar (um comando encontra arquivos e o outro lida com a execução stdin e em pipeline de outra saída de comando). Vamos apenas fingir que não sabemos nada (ou muito pouco) sobre esse comando.

Eu tenho um problema específico: é preciso procurar todos os arquivos com a .jpgextensão e 500KiB (KiB = 1024 bytes, comumente chamado kibibyte) ou mais em uma pasta de servidor ftp.

Primeiro, abra o manual: man find. O SYNOPSISé magro. Vamos procurar coisas dentro do manual: Digite /mais a palavra que você deseja ( size). Ele indexará muitas entradas -sizeque contarão tamanhos específicos. Fiquei preso. Não sei como pesquisar com "mais que" ou "menos que" um determinado tamanho, e o homem não mostra isso para mim.

Vamos tentar e procurar a próxima entrada encontrada pressionando n. ESTÁ BEM. Algo achei interessante: find \( -size +100M -fprintf /root/big.txt %-10s %p\n \). Talvez este exemplo esteja nos mostrando que com -size +100Mele encontrará arquivos com 100 MB ou mais. Como eu poderia confirmar? Indo para o cabeçalho da página de manual e procurando por outras palavras.

Mais uma vez, vamos tentar a palavra greater. Pressionar gnos levará à cabeça da página de manual. /greatere a primeira entrada é:

 Numeric arguments can be specified as

    +n     for **greater** than n,

    -n     for less than n,

     n      for exactly n.

Parece bom. Parece que este bloco do manual confirmou o que suspeitávamos. No entanto, isso não se aplica apenas aos tamanhos de arquivo. Será aplicado a qualquer um nque possa ser encontrado nesta página de manual (como a frase dizia: "Argumentos numéricos podem ser especificados como").

Boa. Vamos encontrar uma maneira de filtrar por nome: g /insensitive. Por quê? Insensível? Wtf? Temos um servidor ftp hipotética, onde "que outro sistema operacional" as pessoas poderia dar um nome de arquivo com extensões como .jpg, .JPG, .JpG. Isso nos levará a:

-ilname pattern
              Like  -lname,  but  the  match  is  case insensitive.  If the -L
              option or the -follow option is in  effect,  this  test  returns
              false unless the symbolic link is broken.

No entanto, depois de pesquisar, lnamevocê verá que isso procurará apenas links simbólicos. Queremos arquivos reais. A próxima entrada:

   -iname pattern
          Like -name, but the match is case insensitive.  For example, the
          patterns `fo*' and `F??' match  the  file  names  `Foo',  `FOO',
          `foo',  `fOo',  etc.   In these patterns, unlike filename expan‐
          sion by the shell, an initial '.' can be matched by  `*'.   That
          is, find -name *bar will match the file `.foobar'.   Please note
          that you should quote patterns as a matter of course,  otherwise
          the shell will expand any wildcard characters in them.

Ótimo. Nem preciso ler -namepara ver que essa -inameé a versão que não diferencia maiúsculas de minúsculas desse argumento. Vamos montar o comando:

Comando: find /ftp/dir/ -size +500k -iname "*.jpg"

O que está implícito aqui: O conhecimento de que o curinga ?representa "qualquer caractere em uma única posição" e *representa "zero ou mais de qualquer caractere". O -nameparâmetro fornecerá um resumo desse conhecimento.

Dicas que se aplicam a todos os comandos

Algumas opções, mnemônicos e "estilo de sintaxe" percorrem todos os comandos, fazendo com que você ganhe algum tempo por não precisar abrir a página de manual. Esses são aprendidos pela prática e os mais comuns são:

• Geralmente, -vsignifica detalhado. -vvvé uma variação "muito, muito detalhada" em alguns softwares.
• Seguindo o padrão POSIX, geralmente um argumento de traço pode ser empilhado. Exemplo: tar -xzvf, cp -Rv.
• Geralmente -Re / ou -rsignifica recursivo.
• Quase todos os comandos têm uma breve ajuda com a --helpopção.
• --version mostra a versão de um software.
• -p, em copiar ou mover utilitários significa "preservar permissões".
• -y significa SIM ou "prossiga sem confirmação" na maioria dos casos.

Observe que os itens acima nem sempre são verdadeiros. Por exemplo, a -ropção pode significar coisas muito diferentes para diferentes softwares. É sempre uma boa idéia verificar e certificar-se de quando um comando pode ser perigoso, mas esses são padrões comuns.

Valores padrão de comandos.

No pedaço de pager desta resposta, vimos que less -isé o pager de man. O comportamento padrão dos comandos nem sempre é mostrado em uma seção separada nas páginas de manual ou na seção mais bem colocada.

Você precisará ler as opções para descobrir os padrões ou, se tiver sorte, digitar /pagero levará a essas informações. Isso também exige que você conheça o conceito de pager (software que rola a página de manual), e isso é algo que você só adquirirá depois de ler muitas páginas de manual.

Por que isso é importante? Isso abrirá sua percepção se você encontrar diferenças no comportamento de rolagem e cor ao ler man(1)no Linux ( less -ispager) ou no FreeBSD, man(1)por exemplo.

E a SYNOPSISsintaxe?

Depois de obter todas as informações necessárias para executar o comando, você pode combinar opções, argumentos de opção e operandos em linha para fazer seu trabalho. Visão geral dos conceitos:

• As opções são as opções que determinam o comportamento de um comando. " Faça isso " " não faça isso " ou " aja dessa maneira ". Muitas vezes chamado de switches.
• Os argumentos das opções são usados ​​na maioria dos casos quando uma opção não é binária (liga / desliga) como -tna montagem, que especifica o tipo de um sistema de arquivos ( -t iso9660, -t ext2). " Faça isso com os olhos fechados " ou " alimente os animais, mas apenas os leões ". Também chamado de argumentos.
• Operandos são coisas sobre as quais você deseja que esse comando atue. Se você usar cat file.txt, o operando é um arquivo dentro do diretório atual e seu conteúdo será mostrado em STDOUT. lsé um comando em que um operando é opcional. Os três pontos após o operando informam implicitamente que catpodem atuar em vários operandos (arquivos) ao mesmo tempo. Você pode perceber que alguns comandos definiram que tipo de operando ele usará. Exemplo:cat [OPTION] [FILE]...

Coisas relacionadas à sinopse:

• Compreender a sinopse na página de manual

Quando esse método não funcionará?

• Manpages que não têm exemplos
• Manpages em que as opções têm uma breve explicação
• Quando você usa palavras-chave genéricas como and, to, fordentro das manpages
• Páginas de manual que não estão instaladas. Parece ser óbvio, mas, se você não tiver lftp(e suas páginas de manual) instaladas, não poderá saber que é uma opção adequada como um cliente ftp mais sofisticado executandoman -k ftp

Em alguns casos, os exemplos serão bem simples, e você precisará executar algumas execuções do seu comando para testar ou, no pior dos casos, pesquisar no Google.

Outros: Linguagens de programação e seus módulos:

Se você estiver programando ou apenas criando scripts, lembre-se de que algumas linguagens possuem seus próprios sistemas de páginas de manual, como perl( perldocs), python ( pydocs), etc., mantendo informações específicas sobre métodos / funções, variáveis, comportamento e outras informações importantes sobre o módulo você está tentando usar e aprender. Isso foi útil para mim quando eu estava criando um script para baixar emails IMAP não lidos usando o perl Mail::IMAPClientmódulo.

Você terá que descobrir essas páginas de manual específicas usando man -kou pesquisando online. Exemplos:

[root@host ~]# man -k doc | grep perl
perldoc              (1)  - Look up Perl documentation in Pod format


[root@host ~]# perldoc Mail::IMAPClient
IMAPCLIENT(1)         User Contributed Perl Documentation        IMAPCLIENT(1)

NAME
       Mail::IMAPClient - An IMAP Client API

SYNOPSIS
         use Mail::IMAPClient;

         my $imap = Mail::IMAPClient->new(
           Server   => ’localhost’,
           User     => ’username’,
           Password => ’password’,
           Ssl      => 1,
           Uid      => 1,
         );

... toneladas de outras coisas aqui, com seções como uma página de manual regular ...

Com python:

[root@host ~]# pydoc sys
Help on built-in module sys:

NAME
    sys

FILE
    (built-in)

MODULE DOCS
    http://www.python.org/doc/current/lib/module-sys.html

DESCRIPTION
    This module provides access to some objects used or maintained by the
    interpreter and to functions that interact strongly with the interpreter.
...again, another full-featured manpage with interesting info...

Ou, a help()função dentro do shell python se você quiser ler mais detalhes de algum objeto:

nwildner@host:~$ python3.6
Python 3.6.7 (default, Oct 21 2018, 08:08:16)
[GCC 8.2.0] on linux
Type "help", "copyright", "credits" or "license" for more information.
>>> help(round)

Help on built-in function round in module builtins:

round(...)
    round(number[, ndigits]) -> number

    Round a number to a given precision in decimal digits (default 0 digits).
    This returns an int when called with one argument, otherwise the
    same type as the number. ndigits may be negative.

Bônus: O wtfcomando pode ajudá-lo com acrônimos e funciona como whatisse nenhum acrônimo em seu banco de dados fosse encontrado, mas o que você está pesquisando faz parte do banco de dados man. No Debian, este comando faz parte do bsdgamespacote. Exemplos:

nwildner@host:~$ wtf rtfm
RTFM: read the fine/fucking manual
nwildner@host:~$ wtf afaik
AFAIK: as far as I know
nwildner@host:~$ wtf afak
Gee...  I don't know what afak means...
nwildner@host:~$ wtf tcp
tcp: tcp (7)              - TCP protocol.
nwildner@host:~$ wtf systemd
systemd: systemd (1)          - systemd system and service manager

Isso é bem explicado em man man:

   The following conventions apply to the SYNOPSIS section and can be used
   as a guide in other sections.

   bold text          type exactly as shown.
   italic text        replace with appropriate argument.
   [-abc]             any or all arguments within [ ] are optional.
   -a|-b              options delimited by | cannot be used together.

   argument ...       argument is repeatable.
   [expression] ...   entire expression within [ ] is repeatable.

Quanto a como você deve escrever um comando válido a partir disso, bem, você não é. A sinopse é útil quando você sabe como um comando funciona. Pode ajudá-lo a atualizar sua memória. Para entender como o comando funciona, você deve ler a página do manual. Especialmente as descrições das opções e a seção de exemplos.

Às vezes a sinopse é suficiente. Por exemplo, em man ls:

SYNOPSIS
       ls [OPTION]... [FILE]...

Outras vezes, é inútil, a menos que você já saiba como usar o comando em questão. Por exemplo man dd:

   dd [OPERAND]...
   dd OPTION

Portanto, em conclusão, não se preocupe se você não receber a sinopse. Isso é normal. Leia a própria página do manual.

Algumas noções básicas para entender a sinopse

• cada um [foo]representa argumento ou parâmetro opcional.
• quando a [foo [ bar ] ]sintaxe é usada, você pode usar foo e adicionar barra.
• O parâmetro opção opcional é usado dessa maneira [ -S size ], informando que o argumento -S está aguardando um tamanho obrigatório.

Por exemplo : foo [-S size ] filename ...

significa

• comando é foo
• parâmetro opcional -Spode ser usado, você deve informar size(o nome lhe dá uma dica)
• argumento obrigatório é filename(isso também dá uma dica, veja man mkdir)
• reticências ...informam que você pode usar vários arquivos.

Você ainda precisa se aprofundar na página de manual para entender a opção (no meu exemplo de exemplo acima, -S sizesobre o que é)

manpáginas normalmente são exibidas lesshoje em dia. Isso torna possível pesquisar por eles. Eu não me incomodaria com a sinopse, principalmente porque você tem uma linha de comando específica que deseja entender.

Pressione o botão /e comece a digitar -Ie depois Enter. O primeiro hit estará na sinopse, o segundo (use npara o próximo) fornece a explicação detalhada para -I.

Uma coisa importante a lembrar é que você não pode apenas olhar o manual para um comando, no caso de comandos que executam outros comandos.

Para o seu comando de exemplo

locate something | xargs -I {} bash -c "if [ -d "{}" ]; then echo {}; fi"

Você precisa de informações não apenas xargsmas também bashe [(isso pode estar na página de testmanual). Você também pode precisar de informações em seu shell (provavelmente também do bash) para as regras de cotação, pois seu comando inclui uma cadeia de caracteres citada complexa. Já posso lhe dizer que o argumento citado está errado (e errado de uma maneira que só aparecerá quando você encontrar um arquivo com espaços no nome); o interior "{}"provavelmente deveria ser '{}'.

Então, primeiro você deve consultar a página de manual do xargs e ver o [-I replace-str]que -I {}significa e o [command [initial-arguments]]que bashe tudo depois. Em seguida, consulte a página de bashmanual para saber o que -cfaz, etc.

Adicionando as ótimas respostas já dadas:

1) Se você estiver interessado em um utilitário gnu, especialmente aqueles como sede grep, às vezes, usar o infocomando exibirá uma versão bastante expandida das informações do comando. sed, por exemplo, possui uma seção detalhada sobre como escrever expressões regulares e outra seção com alguns exemplos de uso muito complexos.

2) É um "manual". Um manual foi desenvolvido principalmente para ajudá-lo a se lembrar dos detalhes de algo que você já entende. Ele foi projetado para que você possa obter os detalhes necessários rapidamente e sair. (E muitos não têm exemplos de uso ou apenas triviais.)

Quando eu preciso de aprender algo novo, mesmo uma pequena característica de um comando que não está claro para mim, eu vou para a web e pesquisar usando as melhores palavras-chave que posso pensar (por exemplo Linux xargs) e adicione a palavra howto, examplesou tutorial. Isso geralmente é bastante produtivo.

Normalmente, uso o duckduckgo porque mantém minha privacidade, mas se preciso de mais controle sobre minhas pesquisas, uso o Google porque posso dizer apenas para pesquisar em um site ou retornar apenas resultados do ano passado. (Ele tem muitas outras opções de pesquisa avançada. Você pode pesquisá-las no Google.;))

Outra dica:

Para comandos que eu refiro frequentemente, eu salvo a página de manual em um arquivo de texto

man bash > bashman.txt

e carrego esse arquivo em outra janela no meu editor de texto para que eu possa alternar entre copiar e colar, etc. Normalmente, faço o arquivo somente para leitura, para não acabar mutilando por acidente, mas como é meu cópia pessoal, eu poderia editá-lo da maneira que quisesse, adicionando tags para encontrar uma seção com mais facilidade ou até adicionando minhas próprias anotações ou exemplos.

A única desvantagem disso é que a página de manual original pode ser atualizada e minha cópia é estática.

Para obter uma ajuda rápida com seu comando específico, você pode usar o Explain Shell . Por exemplo, seu comando . Após obter o primeiro entendimento de alto nível de como isso funciona, você deve prosseguir com as páginas de manual, conforme as outras respostas recomendam.

Existem duas ferramentas úteis para aprender mais sobre os comandos linux:

1. cheatexibirá a opção freqüentemente usada para uma linha de comando. Além disso, você pode adicionar o seu próprio command + optionpara ser exibido através cheatde um comando específico.
2. bropagesferramenta fornece algum exemplo para uma linha de comando, é possível adicionar seu próprio exemplo ou fazer um upvote / downvote do exemplo fornecido depois de obter o código de verificação bro thanks. O comando com voto obrigatório aparecerá na parte superior da bropágina.

Sugiro tldruma ferramenta abrangente para homens. Páginas de manual simplificadas e orientadas pela comunidade. No Ubuntu você pode instalá-lo via snap, mas também possui versões para outras distribuições. Ele também fornece vários exemplos de usos comuns. 100% recomendado.

> Estou procurando ajuda para interpretar uma página de manual para entender comandos complicados.

Eu acho que esse é o mal-entendido aqui. O que torna o Linux / UNIX tão poderoso é que você pode construir comandos muito longos e eficazes redirecionando, por exemplo, o stdout de um comando (aqui locate) para o stdin de outro (aqui xargs) através de um canal ( |). Portanto, como o Random832 disse corretamente, você não encontrará uma única página de manual que explique o que seu comando de exemplo faz.

Eu recomendo que você leia um guia de script de shell do Linux; o Advanced Bash-Scripting Guide é um excelente documento. Por favor, não se deixe intimidar por isso; dominar o Linux requer anos e é um processo interminável, mas você pode aprender o básico em um período de tempo razoável.

Em seguida, consulte as páginas de manual quando precisar conhecer os detalhes de um comando específico.

Uma vez que você entenda tudo, vale a pena ler Commandlinefu e Bash One-Liners para obter bons exemplos.

Para procurar algo específico nos comandos em uma página de manual, você pode usar:

man echo | grep output.

Mas, para procurar opções (por exemplo -n), você deve usá-lo desta maneira:

man echo | grep -- -n