Społecznościowe manuale
Internet 3rd Jul 2015
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