Nagłówki w TypeFriendly

[bigzbig]

W dokumentacji przeczytałem, że nagłówki w TypeFriendly są w trakcie generowania automatycznie obniżane o jeden z uwagi na ważność tytułu artykułu.
Osobiście uważam, że jeśli chodzi o wyróżnienie graficzne to można to było rozwiązać nadając tytułowi artykułu odpowiednią klasę i odpowiednio go wyeksponować.
Znaczenie jakie to ma z punktu widzenia indeksowania w wyszukiwarkach internetowych bym w tym przypadku pozostawił świadomości użytkownika. Zamiast poprawiać użytkownika lepszym wyjściem byłoby umieszczenie komunikatu uświadamiającego, że h1 wykorzystywany jest do tworzenia tytułów artykułów więc zaleca się nie używania tego poziomu w trakcie tworzenia dokumentacji.
Zgodność z Markdownem powinna być w tym przypadku priorytetem.

[eXtreme]

Hm, to była moja decyzja projektowa.

Doszedłem do wniosku, że aby "nie umieszczać komunikatu uświadamiającego" wygodniej będzie obniżyć poziom nagłówków na wyjściu. Od strony pisania tekstu nie ma to znaczenia - znaczenie ma tylko przy ewentualnym tworzeniu nowego wyjścia (CSS). Osobiście nie lubię notacji atx (z użyciem # przed nagłówkiem) , gdyż notacja setext jest lepiej widoczna i wyróżniona w źródle. W przypadku podawania "takiego komunikatu" tracimy praktycznie jeden z poziomów setext, przy moim rozwiązaniu zaś nadal można korzystać z "===", "---" a niżej z "#". Nie oszukujmy się, kto używa h6? :P Jest to tak niski nagłówek że nawet go nie nie uwzględniałem w CSS-ie wyjścia, bo by był dwa razy mniejszy niż rozmiar normalnego akapitu. ;)

Zgodność z Markdownem powinna być w tym przypadku priorytetem.

Już i tak musieliśmy poczynić inne "hard-coded" zmiany w celu dostosowania do wymogów TF. W trunku gałęzi 0.2 leży już rozszerzenie, które pozwola odwoływać się do rozdziałów w postaci [[identyfikator.rodzialu]] (fragment to przetwarzający został "odkopany" z parsera MD, gdyż oryginalnie był "zakomentowany" :P) - co przecież nie jest częścią specyfikacji (tak jak kolorowanie składni czy ramki informacyjne).

Oczywiście sprawa jest dyskusyjna i nie jest to moje ostateczne słowo. Jestem otwarty na sugestie, ale jeśli już, to kroki zostaną podjęte od gałęzi 0.2.

[Zyx]

Według mnie teraz jest lepiej. Składnia Markdowna ma być przede wszystkim przenośna, a wstawiając komunikat ostrzegający taką przenośność paradoksalnie utrudniasz, gdyż jeśli będziesz chciał przenieść doń tekst z innego miejsca lub z dokumentacji w inne miejsce, będziesz musiał poprawiać nagłówki. Ja jestem zwolennikiem jak największego oddzielenia Markdowna od semantyki HTML-a i im szybciej to zacznie być robione, tym większa szansa na powstanie parsera z wyjściem LaTeX i możliwość generowania PDF-ów z TypeFriendly. Inne sytuacje, gdzie to rodzi problemy:
 - Publikacja na stronie internetowej, przecież one też używają nagłówków.
 - Różne miejsca publikacji rezerwują na własne potrzeby różną ilość nagłówków.

Tak ścisłe trzymanie się stawia pod znakiem zapytania w ogóle stosowanie Markdowna, bo jaki jest pożytek z przenośnego i lekkiego języka, który nie jest przenośny, gdyż z powodu zbyt ścisłego trzymania się wykładni HTML-a trzeba przy publikowaniu tekstu gdzie indziej dokument całkowicie przerabiać?

[eXtreme]

Jak już poruszyłeś Zyx kwestię innych wyjść niż XHTML, to IMO nie będzie to wykonalne dopóki nie napiszemy własnego parsera składni markdown. :P Jeśli już, to musiał by być to konwerter Markdown->XHTML[->LaTeX[->PDF]]

[bigzbig]

Oddzielenie składni markdowna od html-a to jedna sprawa a obniżenie nagłówka to zupełnie inna kwestia. Obniżając nagłówek zmieniasz hierarchię danych. Wpływasz nie tylko na formatowanie, ale też na strukturę. Nie ważne czy będziesz zwracał wynik w postaci xhtml-a, pdf-a, doc-a czy jakiegokolwiek innego formatu. Nagłówek pierwszego poziomu powinien zostać nagłówkiem pierwszego poziomu.

[Zyx]

I właśnie takie rozwiązanie pozwala zachować strukturę dokumentu bez względu na to, gdzie i jak dokument jest wyświetlany.

[bigzbig]

Wręcz przeciwnie - takie rozwiązanie zmienia pierwotną strukturę. Porównał bym to do zamykania niedomkniętych przez usera tagów html. Tylko czy zadaniem TypeFriendly jest naprawianie zepsutej struktury czy jej sformatowanie i wyświetlenie?

[eXtreme]

Czyli proponujesz by tytuł rozdziału (ustawiany przez meta-dane "Title") miał np <h1 class="chapter-title"> resztę zaś zostawić tak jak to parsuje markdown? Powiedzmy, że wtedy h1 zyskałby takie formatowanie jak obecnie ma h2 i tak dalej.

Zauważmy, że osoba, która pisze dokumentację nie powinna przejmować się tym jaki wynik produkuje mu wyjście. Tytuł całego rodziału jest stuprocentowo nadrzędny. W innych parserach spotykałem się np. z taką skladnią:

Code:

Tytuł rodziału
^^^^^^^^^

tak więc tak czy siak mamy tu oddzielenie nagłówka rodziału od nagłówków poszczególnych fragmentów rodziału choć w innej składni.
Prawdę mówiąc nie wiem na prawdę co z tym zrobić. ;) Musiałoby się więcej osób wypowiedzieć, niestety TF póki co mało osób używa.

[bigzbig]

Co z tym zrobić to tak naprawdę zależy do czego ma tak naprawdę służyć ten projekt? Jeśli ma to być tylko i wyłącznie narzędzie do "produkowania" dokumentacji to możesz moim skromnym zdaniem zostawić to jak jest. Jeśli jednak ma z tego powstać coś bardziej uniwersalnego to przemyślał bym tę kwestię jeszcze raz.

[eXtreme]

Co rozumiesz przez kwestię uniweralności?

TypeFriendly to nie parser markdowna, bo nim jest skrypt Michela Fortina, który używamy. Nie jest założeniem używanie tego projektu jako.. no nie wiem.. uniwersalnego parsera dokumentów markdown. Jedynym celem TypeFriendly jest tworzenie dokumentacji, manuali - a atutami miała być prosta konstrukcja i czytelny format wejścia jak i wyjścia - co moim zdaniem udało się nam osiągnąć. Wszystkie zmiany poczynione w rozszerzeniu parsera Michela zostały w celu zastosowania ich w TF. Czy ramki informacyjne mają jakiś sens w normalnej składni MD? Raczej nie, tak samo jak kolorowanie składni - bo oba te elementy przetwarzamy na własnym etapie. To samo jest ze składnią automatycznych linków do [[rozdziałów]] wprowadzaną do gałęzi 0.2 - nie jest elementem składni, ale ułatwi pisanie dokumentacji i zarazem pasuje do konwencji składni markdown (wspomnę znów o "planowanym" wprowadzeniu takiej składni przez Michela ale porzuconej, a wykorzystanej przez nas do własnych celów).

Praserów składni markdown jest wiele, szczególnie w innych językach. W PHP jest niestety tylko dzieło Michela. Każdy z nich wprowadza jakieś udoskonalenia ponad podstawową składnię, część rzeczy rozwiązywana jest inaczej (jak choćby tabelki), więc moim zdaniem wielką zbrodnią nie jest to, że do TF wprowadziliśmy takie zmiany.

Tak więc czym jest ta uniwersalność? Czym chciałbyś, aby był TF?

[Zyx]

Tego typu dyskusja nad (bez obrazy) bzdetami do niczego nikogo nie doprowadzi, a jako podsumowanie dodam, że duuuuuuuuuużo bardziej uniwersalny DocBook XSL Stylesheet jak najbardziej zezwala na podobne zagrywki. W obrębie źródeł jest nagłówek pierwszego poziomu? Jest; od semantyki itd. są właśnie źródła, a wyświetlanie od wyświetlania. Prawdę mówiąc wkurzyłbym się trochę, gdybym w imię źle rozumianej poprawności politycznej musiał przepisywać całą dokumentację, by ją zamieścić u siebie na stronie we własnej szacie graficznej. Gdzie tu uniwersalność? Gdzie przenośność? Gdzie wygoda? TypeFriendly powstał właśnie po to, aby człowiek mógł sobie siąść i zacząć pisać dokumentację bez zajmowania się setkami bzdetów. Racja, system wyjścia musi przestrzegać pewnych zasad, ale nie popadajmy przy tym w paranoję. Na upartego żaden problem dodać odpowiedni przełącznik do konfiguracji, tylko kto będzie z niego korzystać? Garstka fanatyków zapewne.

[bigzbig]

@eXtreme - nie traktuj mojego poprzedniego posta jak zarzutu albo oskarżenia o "zbrodnię". To czym się stanie TypeFriendly zależy tylko od Was albo od Ciebie - nie wiem ile osób uczestniczy w tym projekcie. Jeśli założeniem było uczynić z TF narzędzie do generowania dokumentacji to faktycznie już teraz jest to całkiem fajna biblioteka. Kwestię nagłówków poruszyłem bo wydało mi się to nadmiarowym obejściem problemu, którego tak naprawdę nie ma, Bynajmniej moją intencją nie było rozciągnięcie stosunkowo błahej sprawy do rozmiarów egzystencjonalnego problemu na miarę pytania "dokąd zmierzamy"?

@Zyx - masz rację, że to bzdety - takie moje czepialstwo. Szczerze mówiąc nie sądziłem, że się taka bogata dyskusja z tego zrodzi. Tak po prawdzie jednak gdybyście domyślnie nie obniżali nagłówków i zrobili przełącznik który to robi to też nikt by z niego nie skorzystał, a narzędzie bynajmniej nic by na tym nie straciło.

Ok proponuję zamknąć ten temat bo widzę, że się zaognia  ;)

[eXtreme]

@bigzbig - ubolewam, że mój post został potraktowany jako jakiś.. nie wiem.. agresywny? ;) Nie to było założeniem, po prostu pytałem. :P

Wracają do kwestii - ostatecznie taką sprawę można zrzucić na barki konfiguracji poszczególnego wyjścia, gdy system wyjść ma zostać całkowicie przebudowany w gałęzi 0.2.

EOT w takim razie i nie drążmy tego dalej. ;)