R17-03, ## Documents ##, C++Builder 5


Rozdział 17.
Tworzenie dokumentacji i plików pomocy

Drew Avis

Dziesięć przykazań autora dokumentacji

Rodzaje dokumentacji

Metodologia tworzenia dokumentacji elektronicznej

Formaty plików pomocy

WinHelp - sprawdzony standard

Microsoft HTML Help

Obsługa pomocy w bibliotece VCL

Materiały i narzędzia dla twórców dokumentacji

Chyba każdy użytkownik komputera „zaliczył” już przeglądanie plików pomocy i dokumentacji programu - czy to w poszukiwaniu opisu jakiejś czynności, czy też może informacji o błędzie. Ile razy zdarzało się nam, że odchodziliśmy z kwitkiem albo, co gorsza, uzyskane wiadomości okazywały się niepełne lub nieprawdziwe? Dokumentacja jest jednym z głównych --> źródeł [Author:ts] wiedzy użytkowników o programie i jako taka ma ogromny wpływ na sposób jego postrzegania. Jakość dokumentacji jest bardzo ważnym kryterium wyboru oprogramowania i w coraz większym stopniu uwzględniana jest w opiniach i recenzjach.

Problem jakości dokumentacji ilustruje prawdziwa historia, jaka zdarzyła się podczas tworzenia edytora Microsoft Word 97. Członkowie zespołu projektowego zdecydowali się przeprowadzić wywiad z użytkownikami poprzedniej wersji (Word 95) w celu ustalenia, jakie nowe możliwości i funkcje powinny znaleźć się w programie. Okazało się, że 80 procent życzeń użytkowników… zostało już spełnione. Wymienione przez nich funkcje były dostępne już w Wordzie 95, tyle że mało kto o nich wiedział! Jak widać, kiepskie rozwiązania interfejsu użytkownika i źle napisana dokumentacja potrafią skutecznie ukryć wiele możliwości programu.

Każda aplikacja, niezależnie od jej rozmiaru, wymaga dokumentacji - papierowej, elektronicznej lub obu rodzajów. W rozdziale tym przedstawimy metody tworzenia takiej dokumentacji, używane w tym procesie narzędzia i formaty danych oraz wskazówki dotyczące strategii dokumentowania programów.

Uwaga
Osoby zatrudnione w wielu większych firmach mogą prawdopodobnie pominąć cały ten rozdział, gdyż omówiona w nim tematyka po prostu ich nie dotyczy - tworzeniem dokumentacji zajmują się tam zwykle wyspecjalizowane zespoły. Programiści nie mający dostępu do takich luksusów - pracownicy małych firm, wolni strzelcy i niezależni konsultanci - powinni rozważyć skorzystanie z usług specjalistów (niestety, w warunkach krajowych możliwości w tym zakresie są znacznie mniejsze niż w USA - przyp. tłum.). Tych, którzy starają się robić wszystko we własnym zakresie, a zatem oprócz funkcji programisty, marketingowca, prezesa i księgowego muszą także pełnić rolę skryby, zapraszamy do lektury dalszej części rozdziału.

Dziesięć przykazań autora dokumentacji

Przed zagłębieniem się w techniczne rozważania na temat systemów pomocy i redagowania podręczników spróbujmy przedstawić kilka kluczowych elementów dobrej praktyki tworzenia dokumentacji technicznej. Oto one.

Rodzaje dokumentacji

Jeszcze nie tak dawno pojęcie „dokumentacja” sprowadzało się na ogół do jednej książki zwanej ogólnikowo „podręcznikiem użytkownika”. Dzieło to nader często okazywało się być chaotycznym zbiorem opisów poleceń i wybranych komunikatów o błędach (zwykle nie tych, które akurat się trafiały). Postęp w technologii komputerowej przełożył się jednak również na techniki dokumentowania oprogramowania, a współczesne zestawy dokumentacji, o niebo dojrzalsze od niegdysiejszych „powielaczowych instrukcji”, zawierają liczne, zróżnicowane odmiany dokumentów. Zestawienie rodzajów dokumentacji (podzielonej ogólnie na papierową i elektroniczną) przedstawiamy poniżej (ponieważ wiele produktów dostępnych na rynku oprogramowania nie posiada polskich wersji, w nawiasach podajemy odpowiedniki angielskie - przyp. tłum.).

Elementy dokumentacji papierowej:

Elementy dokumentacji elektronicznej:

Spore koszty druku i coraz większe możliwości elektronicznych systemów dokumentacji sprawiają, że producenci oprogramowania odchodzą od tradycyjnej, papierowej dokumentacji. Coraz więcej materiałów dostarcza się w formie plików i można oczekiwać, że przekaz elektroniczny w niedługim czasie całkowicie wyeliminuje tradycyjne, drukowane podręczniki. Firma Microsoft przyjęła taką strategię, wprowadzając na rynek system Windows 95, wyposażony w jeden tylko (do tego dość cienki) papierowy podręcznik instalacji. Niestety, elektroniczna dokumentacja Windows 95 jest daleka od doskonałości i nie jest chyba najlepszym wzorem do naśladowania.

Metodologia tworzenia dokumentacji elektronicznej

Przed rozpoczęciem prac nad dokumentowaniem aplikacji należy opracować plan realizacji tego zadania. Plan taki powinien precyzować rodzaje informacji przekazywanych użytkownikowi oraz sposób ich przekazywania. Punktem wyjścia jest tu często pytanie: „Kto będzie używał tego programu?”, czyli ustalenie kręgu odbiorców. Minimalny zestaw informacji ogólnych, przeznaczonych dla przeciętnego użytkownika, obejmuje opis głównych procedur (sposobów wykonywania podstawowych zadań), czemu poświęcimy nieco więcej uwagi w punkcie „Pomoc proceduralna” w dalszej części rozdziału. W następnym etapie należy określić rodzaj i zakres przekazywanych użytkownikowi informacji natury ogólnej (koncepcyjnej) i referencyjnej. Krok ten obejmuje ustalenie lokalizacji danych (w głównym pliku pomocy lub w pliku dodatkowym) oraz sposobu ich logicznego połączenia z opisami procedur. Na koniec do rozważenia pozostaje kwestia samouczka i przykładów, ułatwiających użytkownikowi samodzielną naukę obsługi programu.

Przedstawione wcześniej zasady dobrej praktyki tworzenia dokumentacji stosują się w równym stopniu do dokumentów elektronicznych, jednak specyfika tych ostatnich niesie ze sobą kilka czynników, które dodatkowo wpływają na ich organizację.

Kategorie systemów pomocy

Ze względu na zawartość i przeznaczenie systemy pomocy można podzielić na kilka kategorii, spełniających zapotrzebowanie na rozmaite rodzaje informacji (Hackos i Stevens). Jedna z możliwych klasyfikacji opiera się na podziale przekazywanych informacji na cztery kategorie:

Pomoc proceduralna

W systemach pomocy przeznaczonych dla przeciętnych użytkowników dominują informacje natury proceduralnej (zobacz rysunek 17.1), opisujące metody wykonywania konkretnych zadań i zorientowane na uzyskanie określonych wyników. Prawidłowo skonstruowane opisy procedur wykorzystują na ogół wspólny punkt wyjścia (np. ekran główny lub menu główne aplikacji) i zawierają opisy poszczególnych kroków, których wykonanie prowadzi do zrealizowania zadania. Opis każdego kroku powinien zawierać informację o spodziewanym wyniku (np. „Na ekranie pojawi się okno otwarcia pliku”), zaś elementy wymagające uwagi lub ostrożności należy opatrzyć odpowiednimi uwagami.

Rysunek 17.1. Przykład opisu proceduralnego - system pomocy Microsoft Windows 98

Stworzenie dobrego opisu procedury nie jest zadaniem łatwym. Które kroki należy uwzględnić? Ile można założyć na temat wiedzy użytkownika - czy trzeba np. informować go, że do zamknięcia okna służy przycisk Zamknij? Na pytania te - a także na wiele innych - nie ma jednoznacznych i prostych odpowiedzi. Jednym z możliwych rozwiązań jest opisanie procedur w dwóch równoległych, odpowiednio zatytułowanych wersjach - jednej przeznaczonej dla początkujących użytkowników i drugiej - dla ekspertów. Można też zaoferować użytkownikowi tylko wersję „zaawansowaną”, a dodatkowe informacje dla nowicjuszy udostępniać w postaci oddzielnych okienek, dostępnych na żądanie (np. po kliknięciu myszą).

Dwa zasadnicze rodzaje informacji przekazywanych w ramach pomocy proceduralnej to opisy wykonywania zadań i funkcji oraz opisy usuwania usterek. O ile w pierwszym przypadku informacje przekazywane użytkownikowi można określić jako pomocne (ale nie bezwzględnie konieczne), dobrze skonstruowane procedury usuwania usterek okazują się nieocenioną pomocą we wszelkiego rodzaju kryzysach.

Poniżej podajemy kilka wskazówek, przydatnych w tworzeniu dokumentacji typu proceduralnego.

Pomoc referencyjna

Kategoria ta obejmuje informacje nie przeznaczone do nauki i zapamiętania. Powinny one być umieszczone w oddzielnym dokumencie, zorganizowanym w sposób maksymalnie ułatwiający dostęp i przeglądanie (zobacz rysunek 17.2), co narzuca rygorystyczne wymagania w kwestii układu jego zawartości. Informacje typu referencyjnego mają na ogół naturę „abstrakcyjną” i „statyczną”, tj. nie są podawane na podstawie konkretnych zadań i procedur. Dobrze skonstruowany dokument referencyjny powinien być wyczerpujący i w miarę możliwości zawierać objaśnienia wszelkich tematów, jakie mogą pojawić się w danym kontekście. Na przykład słowniczek terminów używanych w programie powinien obejmować wszystkie nazwy i hasła, na jakie użytkownik może natrafić. Przykładami dokumentów referencyjnych mogą być zestawienia wykorzystanych w programie wzorów matematycznych i tabel danych, spisy literatury oraz opisy składni języków programowania.

Rysunek 17.2. Przykład opisu referencyjnego - plik pomocy serwera Local SQL Server ze spisem treści

Pomoc koncepcyjna

Opisy typu koncepcyjnego wyjaśniają mechanizmy działania programów i leżące u ich podstaw zasady (zobacz rysunek 17.3). Zawarte w nich informacje nie są na ogół niezbędne do realizacji konkretnych czynności ad hoc, okazują się natomiast przydatne w dłuższym horyzoncie czasowym. Zadaniem opisu koncepcyjnego jest udostępnienie użytkownikowi wskazówek i materiału pomocnego w wyborze sposobu działania, a także wskazanie opisów (ale nie bezpośrednie opisywanie) konkretnych czynności, które należy podjąć w celu osiągnięcia wybranego celu. Opis koncepcyjny nie musi być wyczerpujący (szczegółowe opisywanie wewnętrznych mechanizmów działania aplikacji mija się z celem), jednak powinien dać użytkownikowi wystarczająco dużo informacji, by mógł on świadomie wykorzystywać odpowiednie funkcje programu do realizacji postawionych przed nim zadań.

Rysunek 17.3. Przykład opisu koncepcyjnego - plik pomocy systemu C++Builder

Pomoc instruktażowa

Zadaniem materiałów instruktażowych jest, jak sama nazwa wskazuje, nauczenie użytkownika metod korzystania z programu. Z tego też względu dokumentacja taka musi zawierać liczne wyjaśnienia celu operacji oraz szczegółowe opisy zagadnień i terminów (zobacz rysunek 17.4). Istotne jest także poinformowanie użytkownika o celu wykładu lub ćwiczenia. Dobrze zaprojektowane dokumenty instruktażowe zawierają także rozbudowane, szczegółowo opisane przykłady i instrukcje, opisujące krok po kroku sposób ich wykonania. Bezpośrednim wyznacznikiem „jakości dydaktycznej” dokumentu jest adekwatność przykładu do zadań wykonywanych w praktyce przez użytkownika. W odróżnieniu od opisów proceduralnych materiały instruktażowe powinny być możliwie najbardziej dosłowne i szczegółowe.

Rysunek 17.4. Przykład opisu instruktażowego - HTML Help Workshop

Formaty plików pomocy

Nazwą „plik pomocy” (ang. help file) określa się odpowiednio sformatowany plik, zawierający dokumentację produktu, wyświetlaną na ekranie przez odpowiedni program. Używane obecnie formaty plików pomocy opisano w tabeli 17.1.

Tabela 17.1. Najpopularniejsze formaty plików pomocy

Nazwa

Opis

Uwagi

WinHelp (Pomoc systemu Windows)

Format skompilowanych plików pomocy opracowany przez firmę Microsoft i używany w systemach z rodziny Windows; aktualnie używana jest wersja 4., obsługiwana w Windows 95, 98, Me, NT 4 i 2000

Pierwszy i wciąż najpopularniejszy format zapisu plików pomocy dla programów przeznaczonych dla Windows. Wersja 4. umożliwia wyświetlanie obrazów zawierających do 256 kolorów, obsługę spisów treści i indeksów, wyszukiwanie dowolnego tekstu w całym dokumencie, użycie słów kluczowych i tematów związanych, użycie łączy i okienek lokalnych (wyskakujących). Chociaż Microsoft oficjalnie zaprzestał prac nad standardem WinHelp, niezależni producenci oferują dodatkowe rozszerzenia (zaawansowane wyszukiwanie, tapety, łącza do stron WWW). Zawartość plików pomocy (.hlp) kompilowana jest z dokumentów tekstowych w formacie RTF.

HTML Help

Format skompilowanych plików pomocy opracowany przez Microsoft i używany w systemach Windows 98, Me i 2000; najnowsza wersja nosi numer 1.3

Format ten zastąpił standard WinHelp, jednak jak na razie nie dorównuje mu dojrzałością rozwiązań i możliwościami funkcjonalnymi. Przeglądarki formatu HTML Help wchodzą standardowo w skład systemów Windows 98 i --> 2000[Author:ts] ; w Windows 95 i NT 4 zawartość plików w formacie HTML Help można wyświetlać za pomocą przeglądarki Internet Explorer (w wersji 4 lub nowszej). Zawartość plików pomocy (.chm) kompilowana jest z dokumentów w formacie HTML.

NetHelp

Standard zapisu plików pomocy, wykorzystujący czysty język HTML, opracowany przez firmę Netscape; obecnie używana jest wersja 2

Standard NetHelp nie zdobył większej popularności, jest jednak konsekwentnie używany w przeglądarkach Netscape. Umożliwia ograniczoną obsługę kontekstowości. Wyświetlanie zawartości plików w formacie NetHelp 2 wymaga przeglądarki Netscape Navigator w wersji 4 lub nowszej.

Niezależne formaty HTML

Standardy wykorzystujące czysty język HTML, opracowane przez niezależne firmy

Standardy te emulują na ogół funkcje dostępne w formacie HTML Help, wykorzystując w tym celu skrypty w języku JavaScript. W odróżnieniu od standardu Microsoftu, zapewniają przenośność. Przykładami mogą tu być system WebHelp firmy RoboHelp oraz InterHelp, opracowany przez firmę ForeHelp.

Java Help

Format wykorzystujący języki HTML i XML, opracowany przez firmę Sun Microsystems

Wymaga zainstalowania maszyny wirtualnej Javy oraz przeglądarki Java Help. Zapewnia pełną przenośność, chociaż najbardziej sprawdza się w aplikacjach napisanych w Javie.

Oprócz opisanych powyżej w użyciu znajduje się wiele innych formatów plików pomocy, nie mających zastosowania do aplikacji tworzonych w C++Builderze. Jako przykłady można tu wymienić formaty Windows CE, Oracle oraz standardy wykorzystywane w systemach Linux i Unix.

WinHelp - sprawdzony standard

Pomimo bogactwa konkurencyjnych formatów, szerokie możliwości i łatwość rozpowszechniania wciąż czynią standard WinHelp najlepszym rozwiązaniem dla większości aplikacji tworzonych w systemie C++Builder. Pliki pomocy zapisane w formacie WinHelp dają się wykorzystywać we wszystkich wersjach systemu Windows (z 16-bitowej wersji 3. można korzystać nawet w systemie Windows 3.1), a wachlarz dostępnych narzędzi do ich tworzenia (również bezpłatnych) jest bardzo obszerny. System WinHelp jest stopniowo wypierany z rynku przez format HTML Help, wprowadzony w systemie Windows 98 i obsługiwany standardowo również w Windows 2000 i Millennium, a także w pakiecie Microsoft Office 2000. Najnowsza wersja standardu, HTML Help 1.3 (udostępniona w Windows 2000), dysponuje sporymi możliwościami, jest jednak trudniejsza w instalacji w systemach innych niż Windows 2000 (jej wykorzystanie wymaga np. obecności w systemie przeglądarki Internet Explorer w wersji co najmniej 4.0).

Z punktu widzenia naszej dyskusji najważniejszą różnicą pomiędzy standardami WinHelp i HTML Help jest zakres ich obsługi w systemie C++Builder. Wszystkie właściwości i metody komponentów VCL związane z obsługą systemu pomocy zorientowane są na wykorzystanie formatu WinHelp. Oznacza to na przykład, że stworzenie kontekstowego systemu pomocy praktycznie nie wymaga pisania dodatkowego kodu. Standard HTML Help obsługiwany jest przez C++Buildera w minimalnym stopniu, chociaż przy odrobinie wysiłku można uzupełnić brakujące funkcje. Narzędzia do tworzenia plików pomocy w formacie WinHelp omówimy nieco dalej, a na razie przyjrzyjmy się możliwościom standardu, zilustrowanym na rysunku 17.5.

Rysunek 17.5. Przykład działania systemu WinHelp - okno główne, dodatkowe i lokalne w systemie pomocy C++Buildera

Oto podstawowe składniki pliku pomocy w systemie WinHelp.

Tematy. Temat (ang. topic) to blok tekstu poświęcony opisowi konkretnego zagadnienia. Posiada on własny tytuł (nagłówek) i jest wyświetlany w głównym oknie systemu pomocy (okno może być podzielone na obszar przewijalny i nieprzewijalny; tytuł jest zwykle wyświetlany w części nieprzewijalnej).

Łącza. Łącze lub odsyłacz (ang. link, jump) to element hipertekstowy, którego wybranie powoduje przejście do innego tematu. W systemie WinHelp łącza wyróżniane są przez wyświetlenie tekstu w kolorze zielonym i jego podkreślenie. Łącza do tzw. lokalnych okienek pomocy (okienek wyskakujących, ang. pop-up window) umożliwiają wyświetlenie „tymczasowych” okienek usuwanych z ekranu po kliknięciu myszą. Tekst takich łączy wyróżniany jest przez wyświetlenie w kolorze zielonym i podkreślenie linią przerywaną.

Spis treści. Spis treści (ang. table of contents, TOC) to wykaz tematów opisanych w pliku pomocy. Jest on prezentowany w postaci drzewa złożonego z ikon w formie książki; kliknięcie ikony powoduje jej „otwarcie” i wyświetlenie kolejnego poziomu, który może zawierać dalsze książki („gałęzie”) lub tematy („liście” drzewa). Spis treści może zawierać odwołania do różnych plików, może także łączyć logicznie związane ze sobą tematy.

Indeks. Indeks jest po prostu spisem haseł (słów kluczowych), których wybranie prowadzi do odpowiedniego tematu.

Mechanizm wyszukiwawczy. System WinHelp obsługuje przeszukiwanie całego tekstu dokumentu (ang. full text search); indeks haseł generowany jest podczas pierwszego odwołania do pliku pomocy i zapisywany w pliku o rozszerzeniu .fts.

Narzędzia do tworzenia plików pomocy

Rynek programów służących do tworzenia plików pomocy jest obecnie zdominowany przez kilka firm. Najważniejszych „zawodników” i ich produkty przedstawiono w tabeli 17.2.

Tabela 17.2. Narzędzia do tworzenia plików pomocy

Narzędzie

Producent

Uwagi

RoboHelp

Bluesky

Pełnowartościowy pakiet do tworzenia plików pomocy, dostępny w kilku wariantach. Wykorzystuje edytor Microsoft Word; generuje pliki w formacie WinHelp, HTML Help i kilku innych.

ForeHelp

ForeFront

Pełnowartościowy pakiet do tworzenia plików pomocy. Wykorzystuje własny edytor dokumentów; generuje pliki w formacie WinHelp i HTML Help.

Doc-To-Help

WexTech

Kompletny pakiet do tworzenia plików pomocy; wykorzystuje edytor Microsoft Word.

WebWorks Publisher

Quadralay

Kompletny (i drogi) pakiet do tworzenia plików pomocy. Wykorzystuje program Adobe FrameMaker; generuje pliki w formacie WinHelp, HTML Help i kilku innych.

Kontekstowość systemu pomocy

Kontekstowość systemu pomocy oznacza zdolność do prezentowania informacji odpowiednich do bieżącego stanu programu. Innymi słowy, system „wie”, który z elementów okna dialogowego, formularza itd., jest w danym momencie aktywny; wywołanie pomocy po wybraniu takiego elementu (wskazaniu go myszą) powoduje wyświetlenie związanych z nim informacji. Kontekstowe mechanizmy pomocy mają zwykle formę:

Podpowiedzi

Podpowiedzi (ang. tooltip) to małe okienka z tekstem, wyświetlane po zatrzymaniu kursora myszy nad danym elementem (np. przyciskiem). Tekst podpowiedzi jest na ogół krótki i zwięźle opisuje przeznaczenie wskazanego obiektu.

Lokalne okienka pomocy

Lokalne okienka pomocy (zwane też okienkami wyskakującymi, ang. pop-up help window) wyświetlane są w wyniku kliknięcia danego elementu prawym przyciskiem myszy lub kliknięcia po uprzednim naciśnięciu przycisku Pomoc (What's This? - przycisk z ikoną pytajnika, znajdujący się w prawym górnym rogu okna). Okienko lokalne zawiera zwykle krótki opis danego obiektu, uzupełniony niekiedy zwięzłym objaśnieniem procedury lub zadania. Przykład pokazano na rysunku 17.6.

Rysunek 17.6. Przykład lokalnego okienka pomocy

Standardowe okna systemu WinHelp

Naciśnięcie klawisza F1 powoduje wyświetlenie okna prezentującego zawartość pliku pomocy programu. Jeżeli dla danego formularza (okna dialogowego) lub jego aktywnego elementu zdefiniowano identyfikator kontekstu, w oknie systemu pomocy zostanie wyświetlony opis odpowiedniego tematu (o ile zamieszczono go w pliku pomocy - przyp. tłum.). Metoda ta nadaje się doskonale do ogólnego prezentowania zadań i możliwości danego okna lub jego elementu.

Informacje wbudowane

Określenie to odnosi się do najprostszego, a także najczęściej niezauważanego sposobu przekazywania użytkownikowi informacji. Mowa tu o tytułach i opisach wyświetlanych w oknach dialogowych, okienkach komunikatów, na przyciskach i innych elementach interfejsu użytkownika, jak również wszelkich innych informacjach tekstowych „zaszytych” bezpośrednio w kodzie aplikacji.

Program Microsoft Help Workshop

W skład pakietu C++Builder wchodzi opracowany przez Microsoft kompilator plików pomocy Help Workshop. Plik wykonywalny programu, hcw.exe, znajduje się w podkatalogu help/tools/. Do tworzenia prostych plików źródłowych dla programu Help Workshop wystarczy dowolny edytor zdolny do zapisywania dokumentów w formacie RTF (Rich Text Format). Metoda taka, chociaż skuteczna, nie jest jednak zalecana w przypadku opracowywania większych pakietów dokumentacji lub plików pomocy, wykorzystujących zaawansowane możliwości formatu WinHelp 4. Podobnie jak tworzenie większych witryn WWW „na piechotę” za pomocą Notatnika, sposób ten jest niezwykle żmudny i podatny na błędy, dlatego też znacznie lepiej jest skorzystać z któregoś z dostępnych na rynku pakietów do tworzenia plików pomocy (narzędzia takie opisano w ostatniej części rozdziału).

Przedstawione na kilku kolejnych stronach wprowadzenie powinno dać Czytelnikom podstawy umożliwiające tworzenie prostych makrodefinicji, automatyzujących działanie edytora tekstu (np. Worda) pod kątem tworzenia dokumentów źródłowych systemu pomocy. Okazuje się zresztą, że właśnie takie podejście stosowane jest w większości narzędzi do tworzenia plików pomocy - kompilatorem jest w nich standardowy program hcw.exe, zaś funkcje samego narzędzia sprowadzają się do tworzenia i manipulowania identyfikatorami tematów, hasłami, odnośnikami itd. (często wykorzystuje się do tego zestaw makrodefinicji zawartych w „nakładce” na edytor tekstu). Stworzone za pomocą edytora dokumenty zapisywane są w formacie RTF, a następnie przekazywane do kompilacji programowi hcw.

Nasza dyskusja ograniczy się do omówienia podstaw działania programu Help Workshop; zainteresowanych dokładniejszymi informacjami odsyłamy do pliku pomocy (hcw.hlp), zawierającego szczegółowe omówienie funkcji systemu WinHelp, opcji kompilatora i kodów błędów. Uzupełnieniem niniejszego wprowadzenia jest przykładowy projekt pliku pomocy, umieszczony w katalogu HelpExample na dołączonej do książki płycie CD-ROM. Zawiera on dokument źródłowy w formacie RTF (help_ex.rtf), plik mapy identyfikatorów (help_ex.map), skrypt projektu (help_ex.hpj) oraz skompilowany plik pomocy (help1.hlp). Na płycie umieszczono również przykładowy projekt aplikacji wykorzystującej stworzony plik pomocy.

Pliki w formacie WinHelp kompilowane są z dokumentów źródłowych zapisanych w formacie RTF. Oprócz zasadniczego tekstu plik źródłowy zawiera dodatkowe informacje (znaczniki) opisujące poszczególne tematy, ich identyfikatory, hasła indeksu, łącza oraz tzw. sekwencje przeglądowe (ang. browse sequence). Znaczniki wstawiane są w postaci przypisów na początku pierwszego wiersza tematu. Chociaż do poprawnego skompilowania dokumentu wystarczy zdefiniować dla każdego tematu niepowtarzalny identyfikator, w większości praktycznych zastosowań niezbędne jest wyposażenie dokumentu w odpowiednie tytuły tematów, hasła indeksu oraz znaczniki sekwencji przeglądowych.

Spróbujmy zatem opisać kolejne etapy składające się na budowę pliku pomocy.

  1. Pierwszym krokiem jest utworzenie pliku tematów. W opisie wykorzystujemy edytor Microsoft Word, jednak można w tym celu użyć dowolnego edytora zdolnego do zapisywania dokumentów w formacie RTF. Po utworzeniu nowego dokumentu należy utworzyć kilka tematów. W tym celu wpisz ich tytuły (podane poniżej) w oddzielnych akapitach (zakończonych znakiem końca akapitu, czyli naciśnięciem klawisza Enter - przyp. tłum.), a po każdym tytule kilka zdań tworzących treść tematu (również w oddzielnym akapicie). Ponieważ nasz plik nie będzie zawierał automatycznie generowanego spisu treści, pierwszym tematem powinno być „Wprowadzenie” lub „Spis treści”. A oto przykładowe tematy:

Wprowadzenie

Pole edycyjne

Pole wyboru

Słowniczek

Na rysunku 17.7. pokazano postać dokumentu po wykonaniu pierwszego kroku i dodaniu znaczników.

Rysunek 17.7. Tworzenie pliku tematów w edytorze Microsoft Word

  1. W tekście każdego tematu trzeba teraz umieścić odpowiednie znaczniki, definiujące jego identyfikator, tytuł i inne atrybuty. W celu utworzenia znacznika musisz umieścić kursor tekstowy na początku wiersza tytułu i wstawić do dokumentu przypis (w Wordzie służy do tego polecenie Wstaw|Przypis - przyp. tłum.). Rodzaj tworzonego znacznika określony jest symbolem odsyłacza przypisu; poszczególne symbole opisano w tabeli 17.3. W treści przypisu wpisz (zależnie od rodzaju tworzonego znacznika) identyfikator, treść tytułu, słowa kluczowe lub identyfikator elementu sekwencji przeglądowej.

Tabela 17.3. Symbole znaczników

Znacznik

Symbol

Przeznaczenie

Uwagi

Identyfikator tematu

#

Jednoznacznie identyfikuje dany temat; używany w łączach (odnośnikach) do określania miejsca docelowego.

Identyfikator jest ciągiem co najwyżej 255 dowolnych znaków (z wyjątkiem: #, =, +, @, *, % i !). W kontekstowych systemach pomocy identyfikatory rozpoczynają się na ogół przedrostkiem --> IDH[Author:ts] _.

Tytuł

$

Definiuje tytuł danego tematu, wyświetlany na kartach spisu treści oraz wyszukiwania.

Długość tytułu nie może przekraczać 255 znaków (wliczając w to spacje).

Słowo kluczowe

K

Definiuje listę słów kluczowych związanych z danym tematem, używaną przy generowaniu indeksu.

Elementy listy rozdziela się średnikami. Pomiędzy średnikami a słowami kluczowymi nie należy umieszczać spacji, lista nie może również zawierać znaków nowego wiersza. Długość pojedynczego słowa kluczowego jest ograniczona do 255 znaków.

Słowo kluczowe typu „A” (A-keyword)

A

Definiuje listę słów kluczowych, łączących dany temat z innymi tematami; używany głównie do obsługi przycisków „Zobacz też...” (See Also).

Elementy listy rozdziela się średnikami. Pomiędzy średnikami a słowami kluczowymi nie należy umieszczać spacji, lista nie może też zawierać znaków nowego wiersza. Długość pojedynczego słowa kluczowego jest ograniczona do 255 znaków.

Identyfikator elementu sekwencji przeglądowej

+

Definiuje porządek wyświetlania tematów, tworzących sekwencję przeglądową (do wyboru tematu służą przyciski << i >>). W plikach pomocy wykorzystuje się na ogół pojedynczą sekwencję.

Identyfikatory elementów nie mogą zawierać znaków: #, =, +, @, *, % i ! oraz spacji; długość identyfikatora ograniczona jest do 50 znaków. Wykorzystanie sekwencji przeglądowych wymaga uzupełnienia okna o przyciski przeglądania (browse buttons). Najprostszy sposób utworzenia sekwencji przeglądowej to umieszczenie „pustego” znacznika + w każdym temacie; układ sekwencji jest w takiej sytuacji określony kolejnością tematów w dokumencie źródłowym.

Identyfikator typu okna

>

Określa rodzaj okna wykorzystywany do prezentacji tematu. W większości przypadków korzysta się z trzech rodzajów okien: okien tematów (głównych), okien procedur oraz okienek lokalnych (pop-up).

Nazwa okna powinna odpowiadać identyfikatorowi zdefiniowanemu w pliku projektu (zobacz krok 7. poniżej). Zawartość tematu wyświetlana jest domyślnie w oknie głównym (nie wymaga to użycia znacznika >).

  1. Następnym etapem jest ustalenie układu graficznego dokumentu. Sposób formatowania dokumentu - użyte kroje i wielkości czcionki, kolory itp. - przekłada się bezpośrednio na wygląd wyświetlanych stron pomocy. Formatując tekst, należy unikać używania czcionek, które mogą być niedostępne w systemie użytkownika (innymi słowy, najlepiej ograniczyć się do standardowych krojów dostępnych w Windows). Problemy sprawiają też tabele, które niezbyt dobrze „tłumaczą się” na format WinHelp (źle działa łamanie kolumn, nie da się wykorzystywać cieniowania i obramowań), dlatego też ich stosowania należy unikać, a jeśli jest już konieczne - używać jak najwęższych tabel i nie stosować widocznego obramowania. Jedynym sposobem na uzyskanie bardziej wymyślnych efektów wizualnych jest zapisanie tabeli w postaci mapy bitowej i umieszczenie jej w dokumencie jako rysunku.

  2. Pora teraz na zdefiniowanie łączy, czyli hipertekstowych odnośników, łączących poszczególne tematy pomiędzy sobą.

  1. Wybierz fragment tekstu lub element graficzny, który chcesz przekształcić w łącze, np. „Więcej informacji można znaleźć w punkcie Tworzenie plików pomocy.”.

  2. Bezpośrednio za tekstem (bez spacji) wpisz identyfikator tematu wskazywanego przez łącze. Jeśli np. identyfikator tematu docelowego to IDH_WRITING_HELP, zapis powinien mieć postać np. „Więcej informacji można znaleźć w punkcie Tworzenie plików pomocyIDH_WRITING_ --> HELP[Author:ts] .”.

  3. Zaznacz cały tekst łącza i sformatuj go, używając podwójnego podkreślenia (zobacz rysunek 17.8). Jeżeli kliknięcie łącza ma wyświetlać okienko lokalne, należy użyć pojedynczego podkreślenia.

  4. Zaznacz identyfikator tematu docelowego (ciąg IDH_WRITING_HELP) i zamień go na tekst ukryty. Powinno to ponownie dać tekst „Więcej informacji można znaleźć w punkcie Tworzenie plików pomocy.”.

Rysunek 17.8. Włączenie podwójnego podkreślenia w edytorze Microsoft Word

  1. Zapisz dokument w formacie RTF (Rich Text Format).

  2. Utwórz plik mapy identyfikatorów. Zawartość tego pliku wiąże tematy pomocy z identyfikatorami kontekstu używanymi w aplikacji. Plik mapy identyfikatorów jest zwykłym plikiem tekstowym (o rozszerzeniu .map) i można go utworzyć za pomocą Worda lub dowolnego innego edytora.

Identyfikatory zdefiniowane w pliku mapy określają kontekst danego tematu i powinny odpowiadać wartości właściwości HelpContext formularza lub odpowiedniego komponentu. Najprostszą metodą powiązania ich z elementami aplikacji jest zdefiniowanie właściwości HelpContext podczas projektowania, a następnie przypisanie do odpowiednich stałych zawartych w pliku mapy. Nazwy tych ostatnich powinny być identyczne z identyfikatorami użytymi w pliku pomocy. C++Builder udostępnia także inne sposoby wywoływania tematów pomocy specyficznych dla komponentów; więcej na ten temat powiemy dalej, w punkcie „Definiowanie lokalnych okienek pomocy”.

Tworzenie mapy identyfikatorów nie jest konieczne - odpowiednie definicje można zapisać bezpośrednio w pliku projektu pomocy (.hpj). Rozwiązanie takie jest wygodne w przypadku małych projektów, jednak dla bardziej rozbudowanych aplikacji najlepiej jest używać oddzielnego pliku (lub plików) .map. Jednym z rozwiązań jest zdefiniowanie oddzielnego pliku mapy dla każdego formularza, dzięki czemu podczas wprowadzania poprawek i aktualizacji można ograniczyć się do zmodyfikowania jednego pliku.

Jak powiedzieliśmy wcześniej, plik mapy jest zwykłym plikiem tekstowym, którego wiersze mają następującą postać:

#define ID_TEMATU wartość-ontekstu

gdzie ID_TEMATU to użyty w dokumencie źródłowym identyfikator danego tematu, zaś wartość-kontekstu to wartość właściwości HelpContext odpowiedniego komponentu. Zawartość przykładowego pliku mapy pokazano poniżej.

/* MojProg.MAP

Identyfikatory tematów dla elementów formularza głównego

*/

#define IDH_OVERVIEW 10 // wprowadzenie

#define IDH_FORM1 20 // temat domyślny dla formularza Form1

#define IDH_EDIT1 30 // pole edycyjne Edit1

#define IDH_CHECK1 40 // pole wyboru Checkbox1

#define IDH_FORM2 50 // temat domyślny dla formularza Form2

#define IDH_EDIT2 60 // pole edycyjne Edit2

Tak utworzony plik należy zapisać w formacie ASCII (zwykły plik tekstowy), używając rozszerzenia .map.

  1. Kolejnym etapem jest utworzenie skryptu projektu i skompilowanie pliku pomocy. W tym celu uruchom program Help Workshop i utwórz nowy projekt poleceniem New-Help Project z menu File. Okno programu pokazano na rysunku 17.9.

Rysunek 17.9. Okno główne programu Microsoft Help Workshop

Dodaj do projektu utworzony wcześniej dokument RTF. W tym celu kliknij przycisk Files, w wyświetlonym oknie dialogowym kliknij Add i wybierz odpowiedni dokument w oknie otwarcia pliku.

Definiowanie przycisków obsługujących sekwencje przeglądowe rozpoczniemy od utworzenia okna pomocy. W tym celu kliknij przycisk Windows i w oknie Create a window wpisz nazwę nowego okna (np. MAIN). W podobny sposób utwórz drugi rodzaj okna, bazujący na typie Error message, który wykorzystamy dla okienek lokalnych. Okno Window properties umożliwia ustalenie właściwości okna, jak: treść paska tytułu, kolor, położenie (bardzo pomocny okazuje się tu przycisk Auto Sizer, umożliwiający manipulowanie rozmiarami i położeniem okna „na żywo”) i wyświetlane przyciski (na karcie Buttons zaznacz pole wyboru Browse).

W celu dołączenia mapy identyfikatorów do projektu kliknij przyciski Map, Include i w oknie Include File wpisz nazwę pliku mapy. Kliknięcie przycisku Add w oknie Map pozwala definiować pojedyncze identyfikatory bezpośrednio w skrypcie, co jest alternatywą dla użycia oddzielnego pliku (zobacz punkt 5.).

Kliknięcie przycisku Save and Compile spowoduje skompilowanie projektu i utworzenie pliku pomocy o rozszerzeniu .hlp.

  1. Ostatnim etapem jest dołączenie pliku pomocy do projektu aplikacji w C++Builderze. W tym celu wydaj polecenie Options z menu Project i wpisz nazwę pliku pomocy w polu Help file na karcie Application. Nazwę tę można także określić w trakcie wykonywania programu za pomocą instrukcji

Application->HelpFile = "PlikPomocy.hlp";

Ustaw właściwości HelpContext wszystkich komponentów zgodnie z odpowiadającymi im identyfikatorami tematów (np. dla komponentu Form1 wartość HelpContext powinna wynosić 20, co wynika z definicji w przytoczonym wcześniej pliku mapy). Użycie tu wartości zero powoduje, iż komponent dziedziczy kontekst rodzica.

Pozostaje już tylko skompilować i przetestować aplikację i jej plik pomocy. Naciśnięcie klawisza F1 po wybraniu danego elementu formularza powinno wyświetlić okno zawierające treść odpowiedniego tematu.

Definiowanie lokalnych okienek pomocy

Lokalne okienka pomocy, określane w języku angielskim mianem pop-up lub What's This? sprawdzają się bardzo dobrze w oknach dialogowych przeznaczonych do wykonywania konkretnych zadań. Umożliwiają przekazanie użytkownikowi informacji na temat poszczególnych elementów okna. Dostęp do pomocy lokalnej uzyskuje się poprzez kliknięcie przycisku Pomoc, położonego w prawym górnym rogu okna i opatrzonego symbolem pytajnika. Wynikiem tej czynności jest zmiana postaci kursora na strzałkę ze znakiem zapytania (stała TCursorType::crHelp o wartości -20). Zmienia się także zachowanie lewego przycisku myszy - kliknięcie elementu okna powoduje wyświetlenie lokalnego okienka pomocy, zawierającego opis elementu (tj. treść tematu pomocy o identyfikatorze zgodnym z wartością HelpContext wskazanego komponentu).

Zasady tworzenia treści lokalnych okienek pomocy są podobne do reguł używanych dla „zwykłych” tematów, należy jednak pamiętać o kilku szczegółach. Definicje tematów wyświetlanych w okienkach lokalnych nie powinny zawierać obszaru nieprzewijalnego - w przypadku jego obecności okienko będzie zawierało wyłącznie tekst w nim zawarty (zwykle tytuł tematu - przyp. tłum.). Obszar nieprzewijalny (ang. non-scrolling region) tworzy się poprzez zablokowanie podziału strony po danym akapicie, tj. nadanie mu atrybutu Razem z następnym. Treść tak sformatowanego akapitu jest stale wyświetlana w górnej (nieprzewijalnej) części okna, podczas gdy pozostałe akapity mogą być przewijane w części dolnej.

Formularz, dla którego chcemy zaimplementować pomoc lokalną, powinien posiadać następujące właściwości:

Rysunek 17.10. Lokalne okienko pomocy w przykładowym programie

Ostrzeżenie
W opisywanym tu przypadku również naciśnięcie klawisza F1 powoduje wyświetlenie okienka lokalnego, co nie zawsze musi nam odpowiadać. Aby uniknąć tego efektu i wyświetlić w takiej sytuacji zwykłe okno pomocy, należy przedefiniować funkcję obsługi zdarzenia OnHelp komponentu, uzupełniając ją o odpowiednie wywołanie metody Application->HelpJump() lub Application->HelpContext().

Dodatkowe możliwości kompilatora Help Workshop

Kompilator Microsoft Help Workshop dysponuje wieloma zaawansowanymi funkcjami, pozwalającymi wzbogacić możliwości tworzonych plików pomocy. Oto kilka z nich.

Microsoft HTML Help

Zawarty w pakiecie C++Builder kompilator Help Workshop pozwala łatwo wyposażyć aplikację w system pomocy oparty na standardzie WinHelp. Programiści decydujący się na użycie formatu HTML Help, będą musieli pobrać odpowiednie narzędzie - program HTML Help Workshop - z witryny firmy Microsoft. Okno główne programu HTML Help Workshop pokazano na rysunku 17.11.

Rysunek 17.11. Program Microsoft HTML Help Workshop

Istotnym ograniczeniem standardu HTML Help jest wymaganie obecności w systemie przeglądarki Microsoft Internet Explorer w wersji co najmniej 4.0. Jeśli idzie o system operacyjny, wymaganym minimum jest Windows 95 lub Windows NT 4. Przeglądarka plików pomocy w formacie HTML Help oraz odpowiednie wersje programu Internet Explorer wchodzą standardowo w skład systemów Windows 98, Millennium i 2000.

Format HTML Help wykorzystuje kompresję danych ze współczynnikiem porównywalnym z osiągami formatu ZIP. Umożliwia to np. pakowanie całych witryn WWW i dystrybucję ich w postaci pojedynczych, skompilowanych plików. Program HTML Help Workshop umożliwia także tłumaczenie plików źródłowych projektów w standardzie WinHelp (dokumenty RTF, pliki spisów treści .cnt oraz skrypty projektów .hpj) na format HTML Help (.chm). Kilka atrakcyjnych rozszerzeń wprowadzonych w nowym standardzie Microsoftu to paski nawigacyjne wyświetlane „na żądanie” po wskazaniu myszą, animowane łącza (technika ta jest powszechnie stosowana w witrynach internetowych), a nawet możliwość odwoływania się do stron WWW bezpośrednio z okna systemu pomocy (zobacz rysunek 17.12). Oparcie przeglądarki plików pomocy na programie Internet Explorer umożliwia wykorzystanie w plikach pomocy skryptów w językach JavaScript i VBScript.

Rysunek 17.12. HTML Help w akcji - pomoc systemu Windows 98

Biorąc pod uwagę powyższe, wykorzystanie formatu HTML Help należy rozważyć w następujących przypadkach:

Obsługa pomocy w bibliotece VCL

Wyposażenie tworzonej w C++Builderze aplikacji w system pomocy w standardzie WinHelp nie nastręcza większych trudności. Niniejszy punkt poświęcimy omówieniu metod i właściwości komponentów VCL związanych z obsługą systemu pomocy.

Właściwości

TWinControl::HelpContext

Właściwość HelpContext jest kluczowym elementem kontekstowego systemu pomocy. Jej wartość identyfikuje temat pomocy wyświetlany w wyniku naciśnięcia klawisza F1 po wybraniu danego komponentu. Użycie wartości zero oznacza przy tym, iż komponent dziedziczy identyfikator kontekstu od swojego rodzica, co pozwala na przypisanie tego samego kontekstu (i tematu pomocy) wszystkim komponentom formularza, panelu lub grupy. Można również użyć tej samej wartości HelpContext dla kilku różnych komponentów.

TApplication::HelpFile

Właściwość ta określa nazwę pliku pomocy wykorzystywanego przez aplikację. Domyślny plik pomocy definiuje się na etapie projektowania, wykorzystując w tym celu pole Help file na karcie Application okna opcji projektu (polecenie Options z menu Project). Zmiana właściwości HelpFile w trakcie wykonywania programu pozwala na dynamiczny wybór pliku pomocy (co przydaje się np. w aplikacjach wielojęzycznych).

TCustomForm::HelpFile

Właściwość ta pozwala przypisać formularzowi plik pomocy inny od wykorzystywanego przez samą aplikację. Mechanizm ten można wykorzystać np. gdy dany formularz (lub zestaw formularzy) wykorzystywany jest w kilku różnych programach. W takiej sytuacji wystarczy stworzyć plik pomocy opisujący formularz i przypisać jego nazwę do właściwości HelpFile obiektu formularza. Naciśnięcie klawisza F1 spowoduje wówczas wyświetlenie nie pliku pomocy aplikacji, lecz „prywatnego” pliku zdefiniowanego dla formularza.

Metody

TApplication::HelpCommand()

Metoda HelpCommand() pozwala programowi odwoływać się bezpośrednio do funkcji systemu WinHelp. Jej deklaracja to:

bool __fastcall HelpCommand(int Command, int Data);

W poniższym przykładzie wywołujemy za jej pomocą spis treści pliku pomocy:

Application->HelpCommand(HELP_CONTENTS, 0);

Polecenia systemu WinHelp zestawiono w tabeli 17.4.

Tabela 17.4. Identyfikatory poleceń systemu WinHelp

Identyfikator polecenia
(Command)

Znaczenie

Argument
(Data)

HELP_COMMAND

Wywołuje makrodefinicję lub polecenie.

Adres łańcucha zawierającego nazwę makra (w przypadku użycia kilku nazw, należy rozdzielić je dwukropkami lub średnikami). Dla niektórych makr konieczne jest użycie „krótkiej” nazwy, bowiem WinHelp nie obsługuje poprawnie wszystkich „długich” nazw

HELP_CONTENTS

Wyświetla temat zawierający spis treści pliku pomocy (określony zawartością pola CONTENTS w sekcji [OPTIONS] skryptu). Polecenie to jest obecnie przestarzałe; zalecaną metodą jest użycie pliku spisu treści (.cnt) i polecenia HELP_FINDER.

Niewykorzystywany (równy zero)

HELP_CONTEXT

Wyświetla temat określony danym identyfikatorem (zdefiniowanym w sekcji [MAP] skryptu).

32-bitowa liczba całkowita bez znaku, zawierająca kod liczbowy identyfikatora

HELP_CONTEXTMENU

Wyświetla menu kontekstowe pomocy, a następnie lokalne okienko pomocy, zawierające temat odpowiadający wskazanemu elementowi okna.

Adres tablicy par 32-bitowych liczb całkowitych bez znaku. Pierwsza wartość w parze jest identyfikatorem elementu okna, druga - wartością liczbową identyfikatora tematu

HELP_CONTEXTPOPUP

Wyświetla lokalne okienko pomocy, zawierające temat określony identyfikatorem kontekstu (zdefiniowanym w sekcji [MAP] skryptu).

Wartość liczbowa identyfikatora (32-bitowa liczba całkowita bez znaku)

HELP_FINDER

Wyświetla okno tematów pomocy.

Niewykorzystywany (równy zero)

HELP_FORCEFILE

Wymusza wyświetlenie zawartości właściwego pliku pomocy (jeśli używany jest prawidłowy plik, nie robi nic).

Niewykorzystywany (równy zero)

HELP_HELPONHELP

Wyświetla informacje o korzystaniu z systemu pomocy (o ile zawierający je plik WINHLP32.HLP jest dostępny).

Niewykorzystywany (równy zero)

HELP_INDEX

Wyświetla temat zawierający spis treści (identyfikowany wartością pola CONTENTS w sekcji [OPTIONS] skryptu). Polecenie to jest obecnie przestarzałe; zalecaną metodą jest użycie pliku spisu treści (.cnt) i polecenia HELP_FINDER.

Niewykorzystywany (równy zero)

HELP_KEY

Wyświetla temat identyfikowany podanym słowem kluczowym (w przypadku dokładnego dopasowania); w przypadku dopasowania częściowego wybiera pierwsze pasujące hasło na liście słów kluczowych. Jeśli słowo występuje w kilku tematach, wyświetla okno, zawierające ich listę.

Adres łańcucha zawierającego słowo lub słowa kluczowe (rozdzielone średnikami)

HELP_MULTIKEY

Wyświetla temat identyfikowany słowem kluczowym zawartym w alternatywnej tablicy haseł.

Adres struktury typu MULTIKEYHELP określającej przeszukiwaną tablicę haseł oraz szukane słowo kluczowe

HELP_PARTIALKEY

Wyświetla temat identyfikowany podanym słowem kluczowym (jeśli znaleziono dokładne dopasowanie); w przypadku dopasowania częściowego wybiera pierwsze pasujące hasło na liście słów kluczowych. Jeżeli słowo występuje w kilku tematach, wyświetla okno, zawierające ich listę.

Adres łańcucha zawierającego słowo lub słowa kluczowe (rozdzielone średnikami). Podanie pustego łańcucha powoduje wyświetlenie indeksu haseł.

HELP_QUIT

Kończy pracę systemu pomocy (o ile nie korzystają z niego inne programy).

Niewykorzystywany (równy zero)

HELP_SETCONTENTS

Definiuje temat zawierający spis treści, wyświetlany w przypadku, gdy dla danego pliku nie zdefiniowano pliku .cnt (zobacz polecenia HELP_CONTENTS i HELP_INDEX).

32-bitowa liczba całkowita bez znaku zawierająca kod liczbowy identyfikatora tematu

HELP_SETPOPUP_POS

Ustala położenie wyświetlania okienek lokalnych (wyskakujących).

Adres struktury typu POINTS określającej współrzędne okienek (współrzędne używane są do „symulowania” położenia kursora myszy w chwili wyświetlania okienka)

HELP_SETWINPOS

Wyświetla okno pomocy w zadanym położeniu.

Adres struktury typu HELPWININFO, określającej rozmiary i położenie okna głównego lub dodatkowego

HELP_TCARD

Sygnalizuje, że dane polecenie przeznaczone jest dla tzw. okienka ćwiczebnego (ang. training card); właściwe polecenie należy złożyć ze stałą HELP_TCARD za pomocą operatora sumy bitowej.

Zależny od polecenia przekazywanego wraz z HELP_TCARD

HELP_WM_HELP

Wyświetla lokalne okno pomocy, zawierające temat związany z elementem okna o danym uchwycie.

Adres tablicy par 32-bitowych liczb całkowitych bez znaku. Pierwsza wartość w parze jest identyfikatorem elementu okna, druga - wartością liczbową odpowiedniego identyfikatora tematu

TApplication::HelpContext() i TApplication::HelpJump()

Metody te umożliwiają aplikacji bezpośrednie odwoływanie się do tematów pomocy. Parametrem pierwszej z nich jest liczbowa wartość kontekstu, zaś drugiej - identyfikator tematu dany łańcuchem typu AnsiString. Tematy pobierane są z pliku określonego wartością właściwości TApplication::HelpFile. Oto kilka przykładów:

Application->HelpFile = "Pomoc.hlp";

Application->HelpContext(10);

Application->HelpJump("IDH_OVERVIEW");

Zdarzenia

TApplication::OnHelp

Zdarzenie to generowane jest w chwili każdego wywołania funkcji WinHelp z aplikacji (tj. w chwili użycia funkcji HelpContext() lub HelpJump()). Odpowiedni typ funkcyjny zdefiniowany jest następująco:

typedef bool __fastcall (__closure *THelpEvent)(Word Command,

int Data, bool &CallHelp);

Przedefiniowanie funkcji OnHelp() pozwala zapewnić niestandardową obsługę wywołań systemu pomocy. Wartość parametru CallHelp decyduje, czy po obsłużeniu zdarzenia OnHelp zostanie wywołana funkcja WinHelp() (true), czy też nie (false).

Materiały i narzędzia dla twórców dokumentacji

Tworzeniu dokumentacji poświęcono wiele publikacji, zarówno tradycyjnych, jak i elektronicznych. Poniżej przedstawiono kilka godnych polecenia tytułów; jedynym ich mankamentem jest - jak na razie - brak polskich wydań.

Publikacje książkowe

Poniższa lista obejmuje kilka godnych polecenia pozycji książkowych, ogólnie omawiających tworzenie dokumentacji, w tym dwa podręczniki stylistyczne (niestety większość dostępnej literatury jest w języku angielskim - przyp. tłum.). Techniczne aspekty tworzenia plików pomocy opisano w pierwszej z przedstawionych tu publikacji.

Adrian Nowak, Piotr Frej: Tworzenie plików pomocy dla Windows, Helion, Gliwice 1999.

JoAnn T. Hackos, Dawn M. Stevens: Standards for Online Communication, John Wiley and Sons, 1997.

William Horton: Designing and Writing Online Documentation, John Wiley and Sons, 1994.

Robert W. Bly, Gary Blake: How to Write Usable User Documentation, Macmillan Press, 1995.

Microsoft Manual of Style for Technical Publications, Microsoft Press, 1998.

Read Me First! A Style Guide for the Computer Industry, Sun Technical Publications/Prentice

Hall, 1996.

Narzędzia do projektowania systemów pomocy

Na rynku oprogramowania dostępnych jest obecnie wiele pakietów narzędziowych, wspomagających projektowanie systemów pomocy, często oferowanych bezpłatnie lub na zasadzie licencji shareware. Również potentaci w branży, jak np. firmy RoboHelp czy ForeFront, udostępniają swoje produkty poprzez Internet w postaci wersji demonstracyjnych i testowych. Poniżej wymieniono kilkadziesiąt produktów dostępnych w Internecie.

AnetHelp

Cena: 149,95 do 199,95 USD (shareware)

Wymagania: Windows 95

Adres WWW producenta: http://www.anetsoft.com/engl/helptool/prhlptl.htm

Formaty wyjściowe: WinHelp (Windows 3.x, 95), HTML Help, Java Help

Astrohelp

Cena: bezpłatny (freeware)

Wymagania: Windows 3.x lub 95, Word 6, 95 lub 97

Adres WWW producenta: http://www10.pair.com/vsap/AstroHelp.html

Formaty wyjściowe: WinHelp (Windows 3.x i 95)

AuthorIT

Cena: wersja demonstracyjna z ograniczeniem liczby tematów - bezpłatna

Wymagania: Windows 95 lub NT4

Adres WWW producenta: http://www.oscl.com/

Formaty wyjściowe: WinHelp (Windows 95), HTML Help

Doc-To-Help

Cena: 30-dniowa wersja demonstracyjna - bezpłatna

Wymagania: Windows 95 lub NT, Word 95/97

Adres WWW producenta: http://www.wextech.com/doc2help.htm

Formaty wyjściowe: WinHelp (Windows 3.x i 95), HTML Help, JavaHelp

EasyHelp

Cena: 30-dniowa wersja demonstracyjna - bezpłatna

Wymagania: Windows 95 lub NT, Word 6, 95 lub 97

Adres WWW producenta: http://www.eon-solutions.com/easyhelp/easyhelp.htm

Formaty wyjściowe: WinHelp (Windows 95), HTML Help

eAuthor Help

Cena: 30-dniowa wersja demonstracyjna - bezpłatna

Wymagania: Windows 95 lub NT 4

Adres WWW producenta: http://www.hyperact.com/eAuthorHelp.html

Formaty wyjściowe: HTML Help

FAR

Cena: 38 USD (shareware, wersja pełna)

Wymagania: Windows 95

Adres WWW producenta: http://helpware.net/FAR/index.html

Formaty wyjściowe: HTML Help compiled from Web sites

ForeHelp

Cena: 100 do 700 USD; wersje demonstracyjne (okrojone do 20 tematów) dostępne bezpłatnie

Wymagania: Windows 95

Adres WWW producenta: http://www.forehelp.com/

Formaty wyjściowe: HTML Help, WinHelp, wiele innych

HELLLP!

Cena: 30 do 100 USD (shareware)

Wymagania: Windows 95 lub NT 4, Word 97/2000

Adres WWW producenta: http://mindlink.net/Ed_Guy/helllp.html

Formaty wyjściowe: WinHelp (Windows 95)

Help Authoring Expert

Cena: 65 USD (shareware); wersja niezarejestrowana posiada ograniczenie liczby tematów

Wymagania: Windows 95 lub NT 4, Word 95/97

Adres WWW producenta: http://www.stevesamuelson.com

Formaty wyjściowe: WinHelp (Windows 95)

Help Express

Cena: 149 USD (shareware); wersje niezarejestrowane umieszczają w tworzonych plikach reklamy

Wymagania: Windows 95

Adres WWW producenta: http://www.chainware.com/

Formaty wyjściowe: WinHelp (Windows 95)

Help Maker Plus

Cena: 45 USD (shareware); wersje niezarejestrowane posiadają ograniczenie liczby tematów

Wymagania: Windows 3.x, 95 lub 2000, Word 6, 95, 97, 2000

Adres WWW producenta: http://www.exhedra.com/exhedra/helpmakerplus/features.asp

Formaty wyjściowe: WinHelp (Windows 3.1 i 95)

Help Pad

Cena: 80 USD (shareware)

Wymagania: Windows 95

Adres WWW producenta: http://www.gcnet.com/bw/hpad/

Formaty wyjściowe: WinHelp (Windows 95), HTML Help

HelpBreeze

Cena: wersja demonstracyjna (z ograniczeniem liczby tematów) dostępna bezpłatnie

Wymagania: Windows 95 lub NT, Word 6/95

Adres WWW producenta: http://www.solutionsoft.com/

Formaty wyjściowe: WinHelp (Windows 95), HTML Help

Helpburger

Cena: 40 USD (shareware); wersja niezarejestrowana posiada ograniczenie liczby tematów

Wymagania: Windows 95

Adres WWW producenta: http://www.langdaledesigns.co.uk/hb/helpburger.htm

Formaty wyjściowe: WinHelp (Windows 3.1 i 95)

HelpGen

Cena: 40 USD (shareware)

Wymagania: Win 3.x/95 lub NT

Adres WWW producenta: http://www.rimrocksoftware.com/helpgen.html

Formaty wyjściowe: WinHelp (Windows 95)

HelpHikes Pro

Cena: 35 USD (shareware)

Wymagania: Win 3.x/95

Adres WWW producenta: http://web.superb.net/helphikes/

Formaty wyjściowe: WinHelp (Windows 3.1 i 95)

HelpMe

Cena: bezpłatny (freeware)

Wymagania: Windows 95

Adres WWW producenta: http://home.wxs.nl/~verho037/jfprogramming.htm

Formaty wyjściowe: WinHelp (Windows 3.1 i 95)

HTML Help Workshop

Cena: bezpłatny

Wymagania: Windows 95 lub NT 4

Adres WWW producenta: http://msdn.microsoft.com/library/tools/htmlhelp/chm/hh1start.htm

Formaty wyjściowe: HTML Help

HyperText Studio

Cena: wersja demonstracyjna (z ograniczeniem liczby tematów) dostępna bezpłatnie

Wymagania: Windows 95

Adres WWW producenta: http://webnz.com/olson/ProductsFrameset.htm

Formaty wyjściowe: WinHelp (Windows 3.x i 95), HTML Help

JavaHelp

Cena: bezpłatny

Wymagania: Windows 95 lub NT, Solaris, MacOS 8.1

Adres WWW producenta: http://www.javasoft.com/products/javahelp/index.html

Formaty wyjściowe: JavaHelp

NetHelp2

Cena: bezpłatny

Wymagania: Windows 95

Adres WWW producenta: http://home.netscape.com/eng/help/home/home.htm

Formaty wyjściowe: NetHelp2

RoboHELP

Cena: około 2000 USD; 15-dniowa wersja demonstracyjna dostępna bezpłatnie

Wymagania: Windows 95/98

Adres WWW producenta: http://www.ehelp.com

Formaty wyjściowe: większość używanych obecnie formatów

SOS Help! Info-Author

Cena: 30-dniowa wersja demonstracyjna dostępna bezpłatnie

Wymagania: Windows 95

Adres WWW producenta: http://www.lamaura.com/

Formaty wyjściowe: WinHelp (Windows 3.1 i 95)

Visual Help Pro

Cena: 30-dniowa wersja demonstracyjna dostępna bezpłatnie

Wymagania: Windows 95

Adres WWW producenta: http://www.winwareinc.com/

Formaty wyjściowe: WinHelp (Windows 3.1 i 95), HTML Help

Windows Help Designer

Cena: 49 do 79 USD (shareware)

Wymagania: Windows 95 lub NT

Adres WWW producenta: http://www.visagesoft.com/

Formaty wyjściowe: WinHelp (Windows 95), HTML Help

Podsumowanie

Uzupełnienie każdego produktu programowego o odpowiednią dokumentację jest wymogiem bezdyskusyjnym. Warto jednak pamiętać, że zła dokumentacja bywa gorsza od braku jakiejkolwiek dokumentacji.

Spośród wielu rozwiązań i formatów plików, jakie przedstawiliśmy w niniejszym rozdziale, najpopularniejszym w świecie Windows pozostaje nadal standard WinHelp, jakkolwiek firma Microsoft intensywnie lansuje swój nowy produkt - HTML Help. Ponieważ jednak biblioteka VCL zapewnia zautomatyzowaną obsługę funkcji WinHelp, zaś sam C++Builder zawiera kompilator Microsoft Help Workshop, użycie standardu WinHelp w aplikacjach tworzonych w C++Builderze wydaje się być naturalnym wyborem.

Clou projektowania systemu pomocy stanowi jednak nie wybranie odpowiedniego formatu, a zwięzły, klarowny i komunikatywny sposób przedstawiania właściwych i wyczerpujących informacji. Dlatego też strukturę dokumentacji elektronicznej należy planować bardzo starannie, oddzielając od siebie informacje natury proceduralnej, koncepcyjnej, referencyjnej i instruktażowej. Niezbędne jest także ustalenie zakresu wiedzy potrzebnej użytkownikowi. Znajomość jego potrzeb i oczekiwań jest kluczem do opracowania dobrego zestawu dokumentacji elektronicznej.

Ściślej rzecz biorąc, jest on plikiem nagłówkowym języka C, co narzuca odpowiednie wymagania odnośnie składni. Jak łatwo zauważyć, zawartość pliku mapy to po prostu zbiór dyrektyw #define, definiujących stałe symboliczne o nazwach danych identyfikatorami - przyp. tłum.

14

„jedyny” (oryginał) to spora przesada - moje konsultacje z dokumentacją Windows 9x można policzyć na palcach jednej ręki, a korzystam z tego systemu już 5 lat. Są jeszcze książki i nauka przez doświadczenie.

nie ma systemu Windows NT5, jest Windows 2000

ale wcale nie muszą (wbrew oryginałowi) - to kwestia konwencji

oczywiście w oryginale, wbrew temu co wcześniej napisano, przed identyfikatorem jest spacja.

systemu Windows NT 5 nie ma.

w oryginale Word 2000, ale nie mam go w wersji polskiej, Win98SE PL jak najbardziej może być.

w oryginale „słowo”; tablica składa się z wartości typu DWORD

to zdanie przeniosłem z 2. kolumny, bo tu ma większy sens

trochę nie wiem co z tym zrobić, bo nie doszukałem się w polskich wydawnictwach żadnej sensownej książki... ale zawsze można kupić przez Internet albo w APN Promise.


Wyszukiwarka

Podobne podstrony:
R14-03, ## Documents ##, C++Builder 5
R18-03, ## Documents ##, C++Builder 5
R04-03, ## Documents ##, C++Builder 5
R13-03, ## Documents ##, C++Builder 5
R08-03, ## Documents ##, C++Builder 5
R09-03, ## Documents ##, C++Builder 5
R05-03, ## Documents ##, C++Builder 5
R07-03, ## Documents ##, C++Builder 5
R03-03, ## Documents ##, C++Builder 5
R15-03, ## Documents ##, C++Builder 5
R16-03, ## Documents ##, C++Builder 5
R02-03, ## Documents ##, C++Builder 5
R11-03, ## Documents ##, C++Builder 5
r-13-00, ## Documents ##, C++Builder 5
r17-05, ## Documents ##, flash5biblia
r-12-00, ## Documents ##, C++Builder 5
2011 03 03 Document 001
r-10-00, ## Documents ##, C++Builder 5

więcej podobnych podstron