Formatowanie artykułów

Przygotowując serwis WWW zawierający artykuły, warto zadbać o ujednolicenie formatu wszystkich publikacji. W artykule przedstawimy trzy rozwiązania usprawniające redakcję tekstów przeznaczonych do opublikowania na stronach internetowych.

Podstawową zawartością większości stron internetowych są różnego rodzaju artykuły. W większych serwisach są one posegregowane na działy i kategorie, w mniejszych – dostępne za pośrednictwem menu głównego.

Umieszczenie artykułu w serwisie wymaga zazwyczaj pewnego dostosowania
tekstu dostarczonego przez autora. Zmianie ulegają: kod HTML, ścieżki plików (m.in. ilustracji i hiperłączy) oraz style. W zależności od formatu teksu, jego długości oraz od częstotliwości dodawania nowych artykułów, redaktor prowadzący serwis może mieć pełne ręce roboty. Warto proces ten nieco zautomatyzować.

Skrypty omówione w dalszej części artykułu mają za zadanie:

• ujednolicenie i naprawienie formatu HTML,
• ponumerowanie rozdziałów i podrozdziałów,
• oraz opracowanie spisu treści.

Dane wyjściowe

Jako przykładowe dane w artykule wykorzystałem dwanaście moich artykułów na temat języków HTML oraz CSS. Artykuły te ukazały się na łamach Magazynu INTERNET w latach 2003 i 2004. W kodzie HTML artykułów stosuję podstawowe elementy języka HTML:

• nagłówek H1 ustala tytuł tekstu,
• nagłówek H2 służy do oznaczenie autora tekstu,
• akapit P klasy lid zawiera kilka zdań wstępu (określanych redakcyjnym żargonem jako \”lid\”).

W tekście występuje dwustopniowy podział na rozdziały i podrozdziały. Podział ten jest wykonany w oparciu o elementy H3 i H4. Tekst zasadniczy jest zawarty w akapitach P, zaś zmienne, nazwy plików, wyrażenia anglojęzyczne, opcje, nazwy programów czy skróty klawiszowe formatowane są przy użyciu elementu SPAN z klasami \”zmienna\”, \”plik\”, \”ang\”, \”opcja\”, \”program\” oraz \”shortcut\”, na przykład:

Zmienna $plk przechowuje...
...zawartość pliku dane.txt.

Do większych wstawek kodu wykorzystuję element PRE z kilkoma różnymi klasami, zaś ilustracje, listingi, ramki oraz tabelki umieszczam wewnątrz elementów
DIV o klasie ilustracja, listing, ramka, tabela. Przykładowy listing oraz ilustracja zostały przedstawione na listingach 1 oraz 2.

BODY { 
background : rgb(215,251,226); 
text-align : center; 
margin : 50px;
}


Listing 3.Plik nowestyle.css
zawierający definicjestylów

Rys. 6. Strona główna witryny
http://gwz.gajdaw.pl

Struktura skryptu modyfikującego artykuł
Każdy ze skryptów modyfikujących artykuły działa w oparciu o ten sam schemat przetwarzania. Najpierw ustalane są nazwy plików, jakie należy poddać przekształceniu. Do tego celu wywołuję funkcję {stala}glob(){/stala}:

$pliki = glob(\'artykuly/a*.txt\');

Następnie w pętli foreach przetwarzam wszystkie pliki, których nazwy są zawarte w tablicy $pliki. Wewnątrz pętli każdy artykuł jest odczytywany funkcją {stala}file_get_contents(){/stala}, przetwarzany oraz zapisywany (wywołanie
{stala}file_put_contents(){/stala}):

foreach ($pliki as $plik) {
$tmp = file_get_contents($plik);
$html = htmlTagsToLower($tmp);
file_put_contents($plik,$html);
}

Powyższy kod wykonuje konwersję wielkości liter w znacznikach HTML. Funkcja {stala}htmlTagsToLower(){/stala} pobiera jako parametr napis zawierający kod HTML artykułu. Wynikiem działania funkcji jest kod HTML po odpowiedniej
konwersji. Do konwersji dokumentu stosuję zazwyczaj dedykowane funkcje zajmujące się jedną z transformacji. Oprócz wymienionej już funkcji {stala}htmlTagsToLower(){/stala} w skryptach odpowiedzialnych za naprawę kodu

HTML zawarto między innymi funkcje {stala}html­GetBody(){/stala}, {stala}pl_win2iso(){/stala}, {stala}htmlDe­leteComments(){/stala}, {stala}htmlTagsToLo­wer(){/stala} oraz {stala}htmlCorrectBr(){/stala}. Listing 7 przedstawia skrypt, który wstawia do wszystkich artykułów spis treści.

$pliki = glob(\'artykuly/a*.html\');
foreach ($pliki as $plik) {
  echo $plik . \"\n\";
  $tmp = file_get_contents($plik);
  $tablicaTOC = getTableOfContents($tmp);
  $napisTOC = getTableOfContentsAsString($tablicaTOC);
  $tmp = addID($tablicaTOC, $tmp);
  preg_match(\"|(
.*
)[\n\r\t ]*(]*>.*)|Usim\", $tmp, $m);
  $tmp = str_replace($m[1], $m[1] . \"\r\n\r\n\r\n\" . $napisTOC . \"\r\n\r\n\r\n\", $tmp);
  file_put_contents($plik,$tmp);
  flush();
  ob_flush();
}

Trzy etapy przygotowania artykułu

Ujednolicenie formatu HTML

Pierwszym etapem przetwarzania artykułów jest ujednolicenie i naprawienie kodu HTML. Nale­ży dążyć do tego, aby artykuł zawierał poprawny kod XHTML 1.0, zgodny z formatem narzuconym przez redakcję. Zadanie to wygodnie jest wykonać etapami:

1. Wycięcie treści strony (tj. zawartość elementu body).
2. Konwersja polskich znaków.
3. Usunięcie komentarzy HTML.
4. Sprawdzenie poprawności użycia znaków {html}<{/html} oraz {html}>{/html} (na tym założeniu opierają się dalsze algorytmy).
5. Konwersja znaczników HTML: duże litery w małe (zamiast {html}
   –
   {/html}).
6. Ustalenie listy wszystkich użytych znaczników HTML.
7. Naprawa:
   1. BR 
   2. IMG
   3. PRE
   4. THEAD
   5. Usunięcie {html}BR BR{/html}
   6. Modyfikacja ścieżek w elementach IMG
8. Standaryzacja znaczników
9. Trim zawartości elementów P i PRE
10. Przygotowanie stron do walidacji

Powyższa procedura jest oczywiście ukierunkowana
na naprawienie i ujednolicenie konkretnych tekstów (tj. artykułów wymienionych i opisanych w poprzednim punkcie). W przypadku innych tekstów
(złożonych w inny sposób, stosujących inne konwencje, elementy HTML i formaty) procedura ta ulec może pewnym zmianom. Uniwersalne wydają mi się kroki od pierwszego do szóstego oraz krok dziesiąty.

Po wykonaniu pierwszych czterech kroków będziesz
dysponować treścią artykułów pozbawioną komentarzy HTML i zaopatrzoną w odpowiednie ogonki. Co więcej, krok 4 gwarantuje, że dalsze przetwarzanie może opierać się na założeniu, że znaki {html}<{/html} oraz {html}>{/html} są poprawnie użyte. Z kolei krok piąty, konwersja liter dużych na małe w znacznikach
HTML, jest pierwszym etapem konwersji dokumentów HTML na XHTML.

Ujednolicenie formatu artykułów wymaga stwierdzenia, jakie znaczniki zostały wykorzystane
w artykule. Na to pytanie odpowiada skrypt z kroku szóstego. Wyznacza on listę wszystkich wykorzystanych
elementów HTML. Na tej podstawie można przekształcić teksty do spójnego formatu. Jeśli na przykład dostrzeżesz użycie elementów B, możesz je automatycznie przekonwertować na STRONG. Podobnie należy postąpić z elementami stosującymi niedozwolone klasy lub identyfikatory.

Kroki 7, 8 oraz 9 naprawiają kod HTML i konwertują
dokument do języka XHTML. Są to skrypty

przeznaczone do naprawy konkretnych artykułów. Nie są one uniwersalne. Wraz ze zmianą artykułów skrypty te należy wymienić. Wreszcie ostatni krok przygotowuje kompletne dokumenty XHTML przeznaczone do walidacji. W artykułach pojawiają się hiperłącza:

HTML
CSS

ułatwiające walidację kodu XHTML. Jeżeli walidacja
dokumentu przebiegnie poprawnie, to można uznać, że artykuł został naprawiony.
Wszystkie opisane powyżej kroki wykonuje się, stosując funkcje do przetwarzania napisów oraz wyrażenia regularne. Na przykład krok pierwszy, wycięcie treści dokumentu, realizuje funkcja {stala}htmlGetBody() {/stala}przedstawiona na listingu 3.

function htmlGetBody($AStr)
{
if (preg_match(\"|(.*)|Uis\", $AStr, $matches)) {
return $matches[1];
} else {
return false;
}
}

Numeracja rozdziałów

Przystępując do numerowania rozdziałów zakładam, że walidacja dokumentu przebiegła poprawnie. Do oznaczenia rozdziałów i podrozdziałów
w artykułach stosuję elementy h3 oraz h4. Wynika to z faktu, że elementy h1 oraz h2 zarezerwowałem do oznaczenia tytułu oraz autora artykułu. W przypadku stosowania elementów różnych od h3 i h4 do określania struktury tekstu (czyli podziału na rozdziały) podane rozwiązanie należy nieco zmodyfikować.

Fragment jednego z artykułów został przedstawiony
na listingu 4. Wcięcia kodu HTML uwypuklają
strukturę tekstu. Dla przejrzystości, listing ten zawiera wyłącznie tytuły rozdziałów i podrozdziałów
(usunięto z niego treść).

Tekst ten należy oznaczyć, stosując numerację dwupoziomową: numer rozdziału i numer podrozdziału
oddzielone kropką.

Wynik numerowania przykładu z listingu 4 jest widoczny w ramce.

Numerowanie przebiega w dwóch etapach. Najpierw ustalana jest struktura tekstu.

Strony WWW
Języki znacznikowe
Składnia języka HTML 4.01
Znaczniki i elementy
Znaki specjalne
Zagnieżdżanie znaczników
Znaczniki wymagane...
Białe znaki w dokumencie HTML
Atrybuty znaczników
Komentarze w HTML
Struktura dokumentu HTML
Wersje języka HTML...
Nagłówek strony WWW
Treść dokumentu
Podsumowanie

Zadanie to realizuje funkcja {stala}getTableOfContents().{/stala} Stosując wyrażenia regularne, dokonuje ona analizy
tekstu i w wyniku zwraca tablicę, która opisuje podział dokumentu na rozdziały i podrozdziały.
Po wywołaniu:

$tmp[1][0] = Strony WWW
$tmp[2][0] = Języki znacznikowe
$tmp[3][0] = Składnia języka HTML 4.01
...

Jeśli wybrany rozdział zawiera podrozdziały, wówczas tytuły podrozdziałów znajdziesz w dalszych
składowych tablicy {stala}$tmp{/stala}, na przykład:

$tablica[3][1][1] = Znaczniki i elementy
$tablica[3][1][2] = Znaki specjalne
$tablica[3][1][3] = Zagnieżdżanie znaczników
...

Wynik działania funkcji {stala}getTableOfContents(){/stala}
jest przekazywany, wraz z samym artykułem, do funkcji {stala}renumberChapters(){/stala}:

Funkcja{stala} renumberChapters(){/stala} wstawia numery rozdziałów i podrozdziałów. Wewnątrz funkcji, na podstawie tablicy {stala}$tablicaTOC{/stala}, wywoływana jest {stala}funkcja str_replace(){/stala} z odpowiednimi parametrami:

$result = str_replace(\"
{$ATocArray[$i][0]}
\",\"
{$i}. {$ATocArray[$i][0]}
\",
$result
);

Pełny kod funkcji wstawiającej numery stron został przedstawiony na listingu 6.

function renumberChapters($ATocArray, $AText)
{
  $result = $AText;
  $ile = count($ATocArray);
  for ($i = 1; $i <= $ile; $i++) {
    $result = str_replace(\"
{$ATocArray[$i][0]}
\", \"
{$i}. {$ATocArray[$i][0]}
\", $result);
    $ilePodr = count($ATocArray[$i][1]);
    if ($ilePodr > 0) {
      for ($j = 1; $j <= $ilePodr; $j++) {
        $result = str_replace(\"
{$ATocArray[$i][1][$j]}
\", \"
{$i}.{$j} {$ATocArray[$i][1][$j]}
\", $result);
      }
    }
  }
return $result;
}

Spis treści

Praca nad spisem treści, podobnie jak numerowanie rozdziałów, wymaga znajomości struktury tekstu. Wykorzystam do tego omówioną
już funkcję {stala}getTableOfContents(){/stala}. Utworzenie spisu treści polega na wykonaniu trzech operacji:

• po pierwsze, trzeba oznaczyć rozdziały i podrozdziały
  identyfikatorami id;
• po drugie, należy ustalić kod HTML spisu treści,wreszcie po trzecie, kod spisu treści musi zostać umieszczony w artykule.

Najpierw stwórz tablicę $tablicaTOC opisującą strukturę tekstu:

$tablicaTOC = getTableOfContents ($tmp);

Następnie na podstawie tablicy $tablicaTOC
w zmiennej $napisTOC stwórz kod HTML spisu treści:

$napisTOC = getTableOfContentsAsString($tablicaTOC);

Teraz w artykule dodaj atrybuty id elementom h3 oraz h4:

$tmp = addID($tablicaTOC, $tmp);

Każdy rozdział oznaczony elementem {html}h3{/html} otrzyma identyfikator RX, gdzie X jest numerem rozdziału. Na przykład rozdział trzeci, zatytułowany \”Składnia języka HTML 4.01\”, otrzyma identyfikatorR3:

3. Składnia języka HTML 4.01

Natomiast podrozdziały otrzymują identyfikatory
PX-Y (X to numer rozdziału, Y to numer podrozdziału). Podrozdział 3.2 zatytułowany \”Znaki specjalne \” otrzymuje identyfikator P3-2:

3.2 Znaki specjalne

Na koniec, kod HTML spisu treści, zawarty w zmiennej {stala}$napisTOC{/stala}, umieść w artykule:

preg_match(\"|(
.*
)[\n\r\t ]*(]*>.*|Usim\", $tmp, $m);
$tmp = str_replace( $m[1], $m[1] . \"\r\n\r\n\r\n\" . $napisTOC . \"\r\n\r\n\r\n\", $tmp);

Kompletna procedura wstawiająca spis treści do wszystkich artykułów została przedstawiona na listingu 8.

Wynikowa strona

Po wykonaniu opisanych trzech przekształceń artykułów możesz przystąpić do przygotowania strony WWW zawierającej artykuły. Witryna ta stosuje szablon przedstawiony na ilustracji 1. Menu główne strony składa się z czterech opcji: \”Strona główna\”, \”Artykuły\”, \”Adresy\” oraz \”Pobierz\”.
Po wybraniu opcji \”Artykuły\” pojawia się lista wszystkich artykułów zawartych w serwisie. Każdy artykuł jest oznaczony tytułem, po którym następuje akapit wprowadzający. Niebieska strzałka jest hiperłączem do pełnego tekstu artykułu.

Artykuły stosują numerację rozdziałów, zaś spis treści zawarty na początku artykułu ułatwia poruszanie się po tekście.