Jeżeli stale lub okazyjnie możesz nazwać się użytkownikiem Linuksa to z pewnością znany jest Ci problem niezbyt często wykonywanych komend, których składni nigdy się nie pamięta. Oczywiście można zajrzeć do systemowego manuala, ale najczęściej oprócz ściany tekstu objaśniającej nam wszystkie możliwe parametry nie znajdziemy tam zbyt wielu przykładów użycia. Niestety nie tak łatwo jest wpłynąć na treść systemowych manuali dlatego społeczność rozwinęła własne rozwiązania.

Bropages

Bropages to właśnie jeden z projektów starających się wypełnić dziury w manualach skupiając się wyłącznie na przykładach użycia. Sposób działa jest prosty, wystarczy zainstalować napisanego w Ruby klienta.

$ gem install bropages

Następnie używamy go poprzez wywołanie komendy bro jako argument podając nazwę komendy, której przykładów użycia szukamy.

$ bro zip 

5 entries for zip -- submit your own example with "bro add zip" 

# Zips up everything in my current directory recursively into the file archive.zip 
zip -r archive.zip * 

 bro thanks to upvote (36) 
 bro ...no to downvote (0) 

......................................................................................... 

# put README.txt and test.c into the zip file named archive.zip 
zip archive.zip README.txt test.c 

 bro thanks 2 to upvote (15) 
 bro ...no 2 to downvote (0) 

......................................................................................... 

# Recursively zip all files in the directory foo into foo.zip 
zip -r foo foo 

 bro thanks 3 to upvote (8) 
 bro ...no 3 to downvote (2) 

......................................................................................... 

# Recursively zip everything, starting from the current directory, that matches the given pattern into archive.zip 
# Note: the `R` flag is case sensitive! 
zip -R archive "*.png" 
zip --recurse-patterns archive "*.png" 

 bro thanks 4 to upvote (2) 
 bro ...no 4 to downvote (0) 

......................................................................................... 

# Use the `unzip` command to extract a zip file, unlike `tar` and `gzip` where you use a command line argument to decompress 
unzip file.zip # Extracts to current directory 
unzup file.zip -d dir # Extracts to specified directory 

 bro thanks 5 to upvote (1) 
 bro ...no 5 to downvote (0) 

Jeżeli któraś podpowiedź przydała się w naszym przypadku, możemy na nią zagłosować wydając odpowiednią komendę. Jeżeli robimy to po raz pierwszy, będziemy poproszeni o wpisanie kodu autoryzującego wysyłanego na nasz adres e-mail.

$ bro thanks 2 
Bropages.org requires an email address verification to do this 
What's your email address? 
tomasz@karbownicki.com 
Great! We're sending an email to tomasz@karbownicki.com 
Please enter the verification code: xxxxx
Great! You're verified! FYI, your email and code are stored locally in ~/.bro 
You just gave thanks to an entry for zip! 
You rock!

Przykłady użycia danej komendy sortowane są według ilości głosów, dzięki czemu najczęstszej używane przypadki mamy na pierwszym planie.

Oczywiście jeżeli czegoś nam brakuje, obojętnie czy jest to kolejny przykład użycia na istniejącej stronie czy rozpoczęcie nowej strony manuala, możemy to zrobić w bardzo prosty sposób.

$ bro add zip

Po wydaniu tej komendy otworzy nam się domyślny edytor, wraz z szablonem przykładu użycia. Wystarczy uzupełnić i gotowe.

Więcej zastosowań bro możecie obejrzeć w samym bro :-]

$ bro bro

Warto też przejrzeć stronę projektu - bropages.org

TLDR

TLDR (too long didn't read) to kolejne, tym razem wieloplatformowe rozwiązanie problemu nieprzyjaznych manuali. Obecnie mamy do dyspozycji klienty dla:

• Node.js
• Pythona
• Go
• Exilir
• C++
• Androida
• Przeglądarki www

Mi najwygodniej użyć Pythona.

$ pip install tldr

Po instalacji korzystamy analogicznie jak z bro.

$ tldr curl 

# curl 

 Transfers data from or to a server 
 Supports most protocols including HTTP, FTP, POP 

- Download a URL to a file 

 curl "{{URL}}" -o filename 

- send form-encoded data 

 curl --data {{name=bob}} {{http://localhost/form}} 

- send JSON data 

 curl -X POST -H "Content-Type: application/json" -d {{'{"name":"bob"}'}} {{http://localhost/login}} 

- specify an HTTP method 

 curl -X {{DELETE}} {{http://localhost/item/123}} 

- head request 

 curl --head {{http://localhost}} 

- pass a user name and password for server authentication 

 curl -u myusername:mypassword {{http://localhost}}

Współpraca nad treściami manuali odbywa się tu odmiennie niż w bro. Klient nie ma możliwości modyfikacji czy głosowania, jeżeli chcemy zaproponować jakieś zmiany należy klasyczną metodą stworzyć na GitHubie pull request, który następnie przejdzie przez review autorów projektu. Każda komendą w repozytorium to osobny plik w formacie Markdown, więc można szybko odnaleźć miejsce, które chcemy zmodyfikować. Sam klient pobiera manuale bezpośrednio z GitHuba, więc wszystkie dokonane zmiany są od razu po zatwierdzeniu dostępne dla użytkowników.

Strona projektu - github.com/tldr-pages/tldr