Programistyczne Kompendium:Wprowadzenie do wprowadzania

Z Programistyczne Kompendium
Skocz do: nawigacji, wyszukiwania

5 kluczowych zasad

  1. Tutaj jest pomoc https://www.mediawiki.org/wiki/Help:Contents.
  2. Edytować można spontanicznie, nie trzeba robić wszystkiego od razu do końca ani nikogo pytać o zgodę. Mediawiki robi wszystko, żeby to było bezbolesne.
  3. Porządek jest wartością. Zawartość stron powinna być czytelna, co do znaku dokładnie napisana.
  4. Konwencje są ważne, bo "spójność podstawą efektywnego przekazu". Uwagi, wątpliwości i sugestie jak najbardziej mile widziane (prosze wysyłać na sbarzowski[at]talent.edu.pl).
  5. W razie problemów proszę pisać na sbarzowski[at]talent.edu.pl. (Najlepiej po upewnieniu się, że odpowiedzi nie ma w tym dokumencie, konwencjach ani helpie).

Filozofia mediawiki

Mediawiki jest zoptymalizowane do wspólnego wprowadzania, ciągłych zmian i spontanicznych poprawek. Nie trzeba robić wszystkiego od razu dobrze. Jak nie wiadomo jak coś zrobić lepiej zrobić jakoś i potem poprawić niż czekać z wprowadzaniem. Z drugiej strony gdy przeglądamy wiki i zauważymy, że coś jest nie tak warto od razu poprawić. Nie musimy wysyłać nikomu maila, pytać o zgodę albo się jakoś specjalnie koordynować. Wystarczy wprowadzać wiedzę.

Spontaniczna edycja jest istotą wiki.

Mediawiki zakłada, że w zasadzie wszystko jest publiczne, włącznie z historią edycji. To wiele upraszcza od strony technicznej i nam szczególnie nie robi, ale proszę nic poufnego tam nie wrzucać.

Filozofia wikitekstu

Aby zrealizować założenia, stosowany jest specjalny format tworzenia stron tzw. wikitekst.

Edytowanie wikitekstu jest istotnie różne od korzystania z edytorów WYSIWYG jak MS Word czy Libreoffice Writer. Wikitekst to po prostu tekst (ciąg znaków), który jest potem interpretowany przez mediawiki, aby uzyskać formatowanie.

Na przykład, żeby zrobić sekcję w dokumencie w zwykłym WYSIWYG ustawimy tekst na odpowiednio większy, umiejscowimy odstępy, "rysując jak to ma wyglądać". W wikitekście wyrażamy znaczenie "to jest sekcja" szczegóły pozostawiając komputerowi, piszemy:

== Tytuł sekcji ==

I tyle. Wystarczy dodać po obu stronach po dwa znaki == i to już jest interpretowane jako sekcja. I od razu uwzględnione w spisie treści! W podobym duchu możemy stworzyć na przykład listę nieuporządkowaną:

* Pies
* Kot
* Papuga
* Chomik

I mamy taki efekt:

  • Pies
  • Kot
  • Papuga
  • Chomik

Robimy tak trochę jakbyśmy pisali maila, albo z jakiegoś innego powodu woleli nie stosować formatowania, a chcieli stworzyć czytelny dokument z wykorzystaniem wyłącznie tekstu. Oczywiście trzeba się bardzo ściśle trzymać reguł, bo później tekst musi zostać przetworzony w formę do wyświetlenia.

Aby wikitekst był czytelny dla osób, które będą edytować artykuł w przyszłości oraz dla komputera należy zwracać uwagę na szczegóły w szczególności na spacje, nowe linie oraz znaki specjalne. Dokument powinien być co do znaku perfekcyjny, jeżeli zauważymy pomyłkę, bo gdzieś jest dodatkowa spacja w czyimś dokumencie to już to jest warte poprawki. Chodzi o to, żeby dokument wyglądał elegancko i łatwiej było zauważyć prawdziwe błędy jako odstępstwa od normy.

Trzymanie pliku tekstowego w porządku jest rzeczą, która w moim doświadczeniu sprawiała wiele trudności osobom nietechnicznym, ale zapewniam że to jest kwestia chwili przyzwyczajenia. Oczywiście jako ludzie będziemy się czasami mylić, ale co do zasady należy trzymać porządek i zgodnie z tzw. zasadą skautów zostawiać dokument w stanie trochę lepszym niż zastaliśmy.

Wikitekst i podobne technologie mają wiele przewag nad WYSIWYG:

  • Dokładniejsza kontrola nad tym co jest w dokumencie. Znaczna część dokumentów Wordowych jakie widziałem była wypełniona śmieciowymi znakami, literówkami i niespójnym formatowaniem. W wikitekście dokładnie widać co się dzieje.
  • Separacja warstwy semantycznej i prezentacyjnej. Osoba wprowadzająca nie musi przejmować się szczegółami formatowania. Wbrew pozorom eleganckie formatowanie wymaga całkiem umiejętności i uwagi. Robiąc to ręcznie wystarczy, że ktoś nieświadomy przyjdzie i wszystko zepsuje. A tak wszystko jest elegancko.
  • Pisanie w wikitekście bardzo poprawia dostępność (accessibility) aka dostosowanie do potrzeb osób niepełnosprawnych.
  • Szablony i różne automaty bardzo łatwo stosować w wikitekście (przykład quizy o których dalej).
  • Edytowanie wikitekstu i podobnych jest szybsze przy odrobinie wprawy (a już szczególnie pisząc bezwzrokowo).
  • Zachowanie wikitekstu jest znacznie bardziej przewidywalne przy zmianach niż w znanych mi narzędziach WYSIWYG.
  • Edytowanie wikitekstu nie wymaga posiadania, znajmości i stosowania żadnego specjalnego narzędzia. Wystarczy znać proste, intuicyjne i dobrze udokumentowane zasady formatowania.

Jeszcze dla porządku dodam, że umyślnie nie instalowałem edytora WYSIWYG wikitekstu, który w wersji eksperymentalnej pojawił się niedawno na wikipedii. Takie rozwiązanie nadaje się dobrze w przypadku, kiedy chcemy, aby nietechniczne osoby wprowadzały drobne poprawki w prostych dokumentach. W naszym przypadku teksty są techniczne i raczej nikt nietechniczny nie będzie robił merytorycznych poprawek. A przy budowaniu złożoych stron i tak trzeba zrozumieć wikitekst, przynajmniej jeżeli nie chcemy się zakopać.

Strony w mediawiki

Wiki składa się ze stron. Niektóre są tworzone przez mediawiki, ale większość można edytować. Zwyczajne strony po prostu wyświetlają zawartość w wikitekście (przykład Real albo ta strona).

Te zwykłe strony to są artykuły dla użytkownika i wśród nich przebiega domyślne wyszukiwanie.

Te strony należą do głównej przestrzeni nazw i są dla Was najbardziej interesujące, bo tam znajduje się główna zawartość. Jest jednak wiele innych np. pomoc, pliki, dyskusje, użytkownicy. Aby wyszukać w jakiejś przestrzeni nazw trzeba poprzedzić nazwę strony nazwą przestrzeni i dwukropkiem. Na przykład Pomoc: Quizy to pomoc do quizów. Podobnie na przykład Użytkownik: Sbarzowski to strona użytkownika.

Strona główna to w szczególności też jest zwykła strona, którą możecie edytować tak samo jak każdą inną.

A na przykład pasek z lewej strony to MediaWiki: Sidebar.

W dokumentacji mediawiki jest wiele innych przykładów.

Aby edytować stronę należy wejść na nią i kliknąć edytuj w prawym górnym rogu.

Aby stworzyć nową stronę trzeba kliknąć w czerwony link. Jeżeli akurat nie ma takiego pod ręką to możemy po prostu wyszukać nazwę strony, którą chcemy utworzyć i wtedy mediawiki zaproponuje jej utworzenie.

Wszystkie odnośniki do stron zawsze są przez nazwę (tytuł strony), więc do nazewnictwa trzeba przykładać uwagę.

Kluczowe do działania mediawiki są przekierowania między stronami. Na przykład na wikipedii jest przekierowanie z Bruce Wayne na Batman. Z "Umbrina coroides" na "Umbryna piaskowa".

Automatycznie przeskakiwane jest tylko jedno przekierowanie, więc zalecam zawsze linkować bezpośrednio do miejsca docelowego.

Przekierowanie ma dwa zadania:

  • Aliasy nazw artykułów. Na przykład: Pierwsza, Liczba pierwsza to może być ten sam artykuł.
  • Przy zmianie nazw strony, żeby nie zepsuć starych odnośników zostawia się przekierowanie. Należy przy najbliższej edycji jednak te przekierowania ustawić na nową stronę.

Aby strona była przekierowaniem trzeba wpisać: #PATRZ [[gdzie]] Takie samo znaczenie ma #REDIRECT [[gdzie]]. Na przykład zawartość strony Bruce Wayne to może być:

#PATRZ [[Batman]]

Formatowanie

Bardzo skrótowo. Jak chcecie coś więcej to jest mnóstwo dokumentacji na stronie mediawiki.

Nowy akapit robi się pozostawiając pustą linię pomiędzy. Na przykład:

To jest pierwszy akapit. Lorem ipsum dolor sit amet, consectetur adipiscing elit. Aenean et hendrerit libero, vitae malesuada orci. 

A to jest drugi...

Nagłowki robi się umieszczając znaki = po obu stronach. Im więcej tym "głębszy nagłówek", czyli:

== sekcja ==
=== podsekcja ===
==== podpodsekcja ====

Głębiej już lepiej nie wchodzić, ale technicznie można. Spis treści wygeneruje się sam, gdy są przynajmniej cztery sekcje w artykule. Można też wymusić, że się wyświetli albo nie w ramach potrzeb.

Nie należy przeskakiwać poziomów. Tj. podsekcja powinna być w jakiejś sekcji, a podpodsekcja w jakiejś podsekcji (a nie na przykład bezpośrednio w sekcji).

To co jest przed pierwszą sekcją to tekst wprowadzający vide wikipedia, który jest przed ew. spisem treści.

Aby uzyskać emfazę wstawiamy apostrofy.

''pierwszy poziom emfazy'' - italiki

'''drugi poziom emfazy''' - pogrubienie

'''''trzeci poziom emfazy''''' - pogrubienie i pochylenie. Raczej nie stosować.

Lista numerowana:

# pierwszy element
# drugi element
# trzeci element

Efekt:

  1. pierwszy element
  2. drugi element
  3. trzeci element

Lista nieuporządkowana:

* Jabłko
* Pomarańcza
* Kiwi

Efekt:

  • Jabłko
  • Pomarańcza
  • Kiwi

Jak mamy jakiś kawałek tekstu, który musimy umieścić jak jest na stronie to używamy <pre> (preformatted) na przykład, gdy mamy dane wejściowe:

<pre>
3
1 2
2 3
3 4
</pre>

Efekt:

3
1 2
2 3
3 4

Jeżeli chcemy jakiś kawałek kodu w tekście (wewnątrz akapitu) używamy na przykład: Wyrażenie <code>++x</code> w języku C to preinkrementacja. Efekt: Wyrażenie <code>++x w języku C to preinkrementacja.

Jeżeli chcemy jakiś podświetlony kawałek kodu wydzielony z tekstu używamy <source lang="Język do którego podświetlamy">, na przykład: Wikitekst:

<source lang="cpp">
#include <cstdio>

int main()
{
	int n;
	scanf("%d", &n);
	int result = 0;
	for (int i = 0; i < n; ++i) {
		int tmp;
		scanf("%d", &tmp);
		result += tmp;
	}
	printf("%d\n", result);
}
</source>

Efekt:

#include <cstdio>
 
int main()
{
	int n;
	scanf("%d", &n);
	int result = 0;
	for (int i = 0; i < n; ++i) {
		int tmp;
		scanf("%d", &tmp);
		result += tmp;
	}
	printf("%d\n", result);
}

Jako parametr lang przekazujemy język cpp dla C++, c dla C, pascal dla Pascala (http://www.mediawiki.org/wiki/Extension:SyntaxHighlight_GeSHi#Supported_languages).

Linki są kluczowe dla funkcjonawania wiki. Link wewnętrzny bardzo prosto wstawić. Wystarczy napisać [[słowo]], żeby stworzyć napis słowo, który jednocześnie jest linkiem do strony słowo. Na przykład: Real to [[typ]] w języku Pascal. Niestety język polski jest językiem fleksyjnym, więc często musimy linkować coś co się nazywa odrobinę inaczej niż wyrażenie w zdaniu. Wystarczy zrobić [do czego linkujemy|co się pojawia]<nowiki>. Na przykład: <pre>W [[Język programowania|języku programowania]] Pascal są trzy rodzaje [[Pętla|pętli]]...</pre> Efekt: W [[Język programowania|języku programowania]] Pascal są trzy rodzaje [[Pętla|pętli]... Osoby nietechniczne mogły się nie spotkać z "|". Na standardowej klawiaturze qwerty to backslash("\") z shiftem i zapewne, gdzieś nad enterem lub obok backspace. A jak chcecie robić linka na zewnątrz to piszemy po prostu (koniecznie z protokołem tj. http:// lub https://): http://talent.edu.pl http://talent.edu.pl A jak z własnym tesktem to w pojedynczych []: <nowiki> [http://talent.edu.pl Strona Talentu] Strona Talentu

Jest jeszcze mechamizm szablonów (templatów). Sprowadza się to do możliwości wydzielenia tekstu, który powtarza się na wielu stronach. Nie musicie umieć tworzyć szablonów, ale dobrze jakbyście wiedzieli, że są i jak będziecie czuli potrzebę jakiegoś to proszę o info. A do wstawiania quizów i nagłówków przy zadaniach już jakieś przygotowaliśmy. Nie wykluczam następnych.

Używa się ich prosto:

{{Quiz|nazwa_pliku_quizu}} - Wstawia link do quizu. O quizach i plikach więcej później.

Na przykład:

{{Quiz|quiz_o_pascalu.txt}}

{{Zadanie|submit_link=adres_gdzie_można_wysłać_zadanie|description_page=nazwa_strony_z_opracowaniem}} - Wstawia linki do opracowania i submitowania.

Na przykład:

{{Zadanie|submit_link=sio2.talent.edu.pl/task/cośtam|description_page=Opracowanie: Liczby parzyste}}

Niestety ze względu na WCAG musimy unikać matematycznych wzorów. Należy używać w miarę możliwości tego, co jest w unicodzie i też z tym nie świrować.

http://www.mediawiki.org/wiki/Help:Formatting#Inserting_symbols

Stąd można sobie je wziąć. Zwracam szczególną uwagę na znak mniejsze równe, który należy stosować w specyfikacji wejścia.

Wyrażeń z potęgami i indeksów też starajmy się unikać. Jak już ich potrzebujemy to postarajmy się je zrobić zwykłym superscriptem i subscriptem na przykład tak:

x<sup>2</sup> - x2

x<sub>2</sub> - x2

Więcej info:

Testy przykładowe

Do testów przykładowych stosujemy niestandardowe rozszerzenie, którego nie ma poza kompendium.

W najprostszej wersji:

<testinput>
Dane wejściowe
</testinput>
<testoutput>
Dane wyjściowe
</testoutput>

Efekt:

Dla danych wejściowych:

Dane wejściowe

Poprawną odpowiedzią jest:

Dane wyjściowe

I to wystarczy, gdy mamy tylko jeden test. Co, gdy mamy wiele? Musimy je jakoś zgrupować. Do tego celu służą wiersze i kolumny. Wiersze robimy za pomocą testrow, a kolumny testcolumn. Kolumny muszą być w wierszach.

Pełny przykład:

<testrow> <testcolumn> <testinput>
Dane pierwszego testu
</testinput> <testoutput>
Wynik pierwszego testu
</testoutput> </testcolumn>
<testcolumn> <testinput>
Dane drugiego testu
</testinput> <testoutput>
Wynik drugiego testu
I jeszcze jedna linijka
</testoutput> </testcolumn>
<testcolumn> <testinput>
Dane trzeciego testu
Tym razem w dwóch linijkach
</testinput> <testoutput>
Wynik trzeciego testu
</testoutput> </testcolumn>
</testrow>

Huh, trochę dużo tego, ale w sumie to jest bardzo proste. Trzeba oznaczyć grupę testów (testrow), każdy test w grupie (testcolumn) oraz input i output każdego testu. Efekt:

Dla danych wejściowych:

Dane pierwszego testu

Poprawną odpowiedzią jest:

Wynik pierwszego testu

Dla danych wejściowych:

Dane drugiego testu

Poprawną odpowiedzią jest:

Wynik drugiego testu
I jeszcze jedna linijka

Dla danych wejściowych:

Dane trzeciego testu
Tym razem w dwóch linijkach

Poprawną odpowiedzią jest:

Wynik trzeciego testu

Każde wiersz jest niezależny, teraz zrobię wiersz w którym są tylko dwa testy:

Dla danych wejściowych:

input1

Poprawną odpowiedzią jest:

output1 

Wyjaśnienie można tu dodać, czemu nie.

Dla danych wejściowych:

input2

Poprawną odpowiedzią jest:

output2

A tu inny komentarz.

Ostatnia uwaga dotyczy potencjalnego rozjeżdżania się na stronie testów. Czasem może to wyglądać trochę dziwnie, bo pozwalamy przeglądarce robić co chce. W kwestii eleganckiego wyglądu trudno konkurować np. z LaTeXem. Może spróbujemy jakoś to poprawić w kwestii rozjeżdżania na boki. Góra-dół, że na innym poziomie zaczynają się outy jest raczej by-design i dosyć trudne do poprawki, ale jak będzie brzydko jakoś bardzo w praktyce to można poprawić.

Zaletą tego rozwiązania jest to, że można trochę zmieniać jak dokładnie są te testy wyświetlane, bez zmieniania 100 treści.

Gotcha chwilowo są usuwane newliny dodatkowe z początku i końca testu, bo dziwny efekt powodowały. Nie wiem czy ja robiłem coś źle, czy mediawiki. Jakby to był kiedyś problem to wtedy się zastanowimy.

Quizy

Pliki quizu są niezależne od mediawiki. Tylko je tam uploadujemy.

http://213.192.104.234/index.php/Pomoc:Quizy

Format plików quizów to tak naprawdę YAML. Specyfikacja tutaj: http://www.yaml.org/spec/1.2/spec.html, ale nie musi Was ona obchodzić.

Ważne jest zwracanie uwagi na spacje i znaki specjalne. Znaki specjalne można escapować za pomocą \. Polega to na tym, że parser wie, że znak po \ należy traktować jako po prostu ten znak, a nie coś specjalnego. W szczególności \\, żeby wyprodukować \ w wyniku. Może też pomóc stosowanie pojdynczych apostrofów.

Kodowanie znaków utf8.

Ważne - przy aktualizacji quizu wynik nie od razu będzie widoczny. Możecie wejść bezpośrednio o plik quizu, bez interfejsu quizów, żeby zobaczyć czy wasze poprawki już "weszły". W razie problemów z quizami kontaktujcie się z Mateuszem Jurczyńskim <mateuszjurczynski[at]gmail.com>.

Pliki

Wszystkie pliki do mediawiki uploaduje się przez "prześlij plik" po lewej stronie.

Strony specjalne

Mnóstwo użytecznych rzeczy możecie znaleźć w stronach specjalnych. Polecam spojrzeć.

Przerabianie materiałów na mediawiki

Będzie trochę boleć. Mediawiki ma zupełnie inną naturę niż formaty dokumentów:

  • Tutaj strony są silnie powiązane, a pdfy czy doci są zupełnie niezależne.
  • Pdf i poniekąd doci są przygotowane przede wszystkim do druku. Niekoniecznie dobrze pozwalają skalować elementy, tak żeby nadal wszystko było estetyczne i użyteczne.
  • doc to WYSIWYG i 90% użytkowników działa metodą "ten tekst ma być czcionką 30, arialem i czerwony" vs "to jest ostrzeżenie".
  • Pdfy tworzone przez LaTeX nie dają się łatwo kopiować. Tj. często, szczególnie blisko matmy będą się kopiować jakieś dziwne znaki, dodatkowe spacje, a niektóre rzeczy w ogóle nie będą się kopiować. Wynika to z tego, że LaTeX w dużej mierze nie umieszcza w pdfie po prostu tekstu, ale odpowiednio rozmieszcza znaki w celu uzyskania maksymalnie eleganckiego wyglądu.

O ile więc wartość merytoryczna przygotowana jest, to w zasadzie 100% formatowania trzeba wykonać od początku. Nawet tam, gdzie były przygotowane eleganckie pdfy (a może nawet szczególnie tam) trzeba będzie to powtórzyć.

Polecam zawsze najpierw skonwertować to czystego tekstu bez formatowania, a potem zrobić formatowanie w mediawiki. W ten sposób to jest mniej frustrujące.

(Plan był na początku taki, że wszystko będzie od razu na mediawiki, ale coś organizacyjnie nie wyszło i nawet nie wiem za bardzo o co chodzi).

Edytor tekstu

Z jakiegoś powodu na Windowsie nie ma domyślnie zainstalowanego sensownego edytora tekstu. A wygodnie czy to przy poważnych edycjach wikitekstu czy przy edycji quizów z takiego skorzystać jednak. Trzeba sobie więc zainstalować.

Na windowsa polecam: http://notepad-plus-plus.org/ albo http://www.sublimetext.com/ (ten jest przenośny, tj. na Linuksa i Maca też jest, ale za to ma śmieszną licencję Unlimited Trial, ale nie musicie się tym przejmować, możecie po prostu zainstalować).

Użytkownicy Maca, Linuksa, BSD czy czego tam jeszcze na pewno wiedzą czym chcą edytować tekst (Ja (sbarzowski) na Linuksie używam kate, sublime albo vima).

Losowe uwagi

Generalnie w razie niejednoznaczności stosujemy takie konwencje jak na wikipedii.

Potencjalne problemy

Mediawiki czasem zwraca uwagę na wielkie/małe litery, a czasami nie. Nie jestem do końca pewien w jakich kontekstach zwraca, a w jakich nie. Postarajcie się dobrze małych i wielkich liter używać zawsze.

W razie pytań/uwag/problemów

sbarzowski[at]talent.edu.pl