Osadzanie raportów RTF w MS Word

Standardowe możliwości w zakresie generowania dokumentacji projektowej w programie Enterprise Architect są wystarczające tylko dla mało wymagających użytkowników. Każdy, kto próbował w tym zakresie osiągnąć coś więcej niż standardowa konfiguracja napotykał na szereg trudności. Trudności te są związane przede wszystkim z edycją szablonów RTF.
A ja tak na przekór wszystkim najbardziej cenię sobie właśnie funkcjonalność generowania dokumentacji. Wynika to chyba z mojej dawnej pasji, którą kiedyś było DTP. Obecnie, gdy uda mi się wyprodukować ładnie wyglądający raport z EA - pękam z radości.
Zamierzam na tym blogu w kolejnych postach dzielić się z Wami doświadczeniem związanych z raportami RTF.
Pominiemy chyba proste generowanie zwykłych raportów, bo łatwo znaleźć w aplikacji polecenie, które do tego służy. Zaczniemy od opisu możliwości osadzania raportów RTF w dokumencie MS Word.

Poniżej znajdziecie diagram, na którym podjąłem próbę opisania tego sposobu w postaci diagramu UML.

W skrócie działa to następująco.
Generujemy jeden raport z zawartości całego repozytorium. Raport ten może zawierać treści nadmiarowe, których nie zamierzamy umieszczać w docelowym dokumencie.
Tworzymy szablon (szkic) docelowego dokumentu w formacie MS Word. W miejscach, gdzie ma się pojawić treść z raportu wskazujemy ścieżkę na dysku do wygenerowanego raportu i podajemy znacznik (GUID) rozdziału (pakietu).

A teraz opiszę to samo bardziej szczegółowo.

1. Przygotuj szablon dokumentu głównego w programie MS Word (na diagramie wskazany jako klasa Szablon) - czyli utwórz nowy dokument w oparciu o szablon projektowy. Dokument ten może zawierać dowolną formę i treść, która jest do uzyskania w MS Word. Warto, aby taki szablon posiadał zdefiniowany spis treści, nagłówek, stopkę i metryczkę. 
2. Wygeneruj raport w formacie RTF (na diagramie wskazany jako klasa Raport EA) w programie Sparx EA, który zawiera wymaganą treść, która ma pojawić się w docelowym dokumencie. Wskazane jest, aby raport ten został wygenerowany przy użyciu tych samych (lub zbliżonych) styli, które są zastosowane w Szablonie.
3. Otwórz w MS Word Szablon.
4. Postaw kursor w miejscu, w którym chcesz umieścić treść wybranego rozdziału (na diagramie klasa Rozdział).
5. Wstaw zawartość raportu RTF w następujący sposób:
• MS Word 2003: W menu wybierz: Insert --> File (Wstaw --> Plik). Pojawi się okno dialogowe jak poniżej. 





•  MS Word 2007: W menu wybierz: Insert --> Object^--> Text from file... (Wstaw-->Obiekt^-->Tekst z pliku...). Pojawi się podobne okno dialogowe, jak powyżej.
6. Wskaż plik zawierający wygenerowany raport RTF i nie zamykaj tego okna.
7. Uruchom program Sparx Enterprise Architect. W oknie Project Browser kliknij prawym przyciskiem na pakiecie, którego zawartość chcesz umieścić w Docelowym Dokumencie. A następnie wybierz z menu kontekstowego: Documentation --> Copy RTF Bookmark
 


8. Wróć do okna dialogowego w MS Word i naciśnij przycisk Range... (Zakres...). Naciśnij Ctrl+V, aby wkleić identyfikator pakietu z EA, który został skopiowany w poprzednim kroku.



9. Naciśnij trójkącik z prawej strony przycisku Insert (Wstaw), aby wybrać opcję Insert as Link (Wstaw jako łącze). Połączenie raportu w formie linku do pliku pozwala na przeprowadzenie aktualizacji zawartości Docelowego dokumentu po aktualizacji modelu w EA i ponownym wygenerowaniu nowego raportu. W nowo wygenerowanym raporcie identyfikator pakietu nie ulega zmianie, w związku unikamy potrzeby ponownego wstawiania Rozdziału i definiowania zakresu. Aktualizacja następuje po odświeżeniu zawartości dokumentu w MS Word, np. poprzez zaznaczenie całego dokumentu (Ctrl+A) i naciśnięcie przycisku F9. Ten krok można traktować jako opcjonalny.
10. Zawartość raportu RTF dotycząca wybranego pakietu pojawia się w dokumencie MS Word.
11. Kroki od 5 do 10 należy powtórzyć dla pozostałych Rozdziałów.
12. Tak przygotowany dokument można zapisać jako Docelowy dokument pod wybraną nazwą. Dodam, ze zwłaszcza w przypadku, gdy wstawiliśmy zawartość jako łącze, warto pamiętać o odpowiednim wersjonowaniu Docelowego dokumentu.

 Podsumowanie

Zalety tej metody to:

• Możliwość zastosowania standardowego szablonu MS Word wykorzystywanego w projekcie do prezentacji zawartości modelu z EA. Dokumentacja ta ma szanse wyglądać identycznie jak inne dokumenty projektowe.
• Możliwość umieszczania różnych Rozdziałów (fragmentów raportu) oraz nawet różnych Raportów w różnych miejscach w Szablonie.
• Możliwość aktualizacji treści w Docelowym dokumencie MS Word w oparciu o zaktualizowaną zawartość modelu.

Wady to:

• Komplikacja procesu wytwarzania dokumentacji - mamy do czynienia z kilkoma plikami, konieczne jest poprawne wskazanie właściwych identyfikatorów pakietów.
• Wstawienie pliku jako łącze powoduje ustawienie referencji do konkretnej lokalizacji Raportu EA na dysku lokalnym. Nie można Docelowego dokumentu przekazać w takiej formie. Wskazane jest wówczas, aby dokument taki przekazywać w formacie PDF lub zrezygnować z linkowania.
• Nie unikamy konieczności samodzielnego opracowania szablonu RTF zgodnego z Szablonem MS Word. W przypadku wystąpienia odmiennych styli nagłówkowych konieczne jest, aby w Docelowym dokumencie przeformatować je na style zdefiniowane w Szablonie.

W ramach podsumowania chciałbym jeszcze napisać, że ta metoda wydawała mi się słuszna kilka lat temu. Sam zastosowałem ją kilkukrotnie i znalazłem nawet naśladowców, jednak obecnie nie rekomenduję takiego sposobu wytwarzania dokumentacji i w swoich szkoleniach nawet o nim nie wspominam.
Za jakiś czas opiszę szczegółowo funkcjonalność Virtual Documents, która jest pozbawiona opisanych powyżej wad.