1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
|
#use wml::debian::ddp title="DDP Lista DO-ZROBIENIA"
#use wml::debian::translation-check translation="1.11"
<H3>Lista najważniejszych spraw DO-ZROBIENIA:</H3>
<ul>
<li>Utrzymywać aktualną dokumentację
<li>Uzgodnić i udokumentować hierarchię dokumentacji. Zasadniczo, ukończyć
<a href="docpolicy">Politykę Dokumentacji</a> z akceptacją i błogosławieństwem
drużyny Debian Web. Pociągnie to za sobą uporządkowanie położenia plików
na stronie www i w pakietach.
<a href="http://www.debian.org/doc/manuals/ddp-policy/ch-manuals.en.html#s3.5">
Tutaj</a> są dostępne szkice, ale wymagają jeszcze przeglądu.
<li>Stworzyć rozwiązanie do automatycznego zarządzania tłumaczeniami
na stronie, gdzie znajdują się źródła WML.
<li>Wybrać które informacje powinny być załączane na CD oraz
<em>zautomatyzować</em> metodę tworzenia odpowiednich indeksów.
Stosowne informacje znajdują się
<a href="http://www.debian.org/doc/manuals/ddp-policy/ch-manuals.en.html#s3.6">tutaj</A>,
natomiast w CVS są pewne <a href="http://cvs.debian.org/ddp/utils/scripts/?cvsroot=debian-doc">
skrypty</a> wymagające wypolerowania i dodania do zadań crona.
</ul>
<H3>Pomysły:</H3>
<p>Poniżej znajduje się lista wybranych idei, które zostały poruszone na
naszej liście dyskusyjnej. Nie są to jeszcze nasze oficjalne zadania, a
pomysły - mogą być zarówno dobre jak i złe :-)
<br>
<ul>
<li>Umożliwić dostęp do wszystkich stron podręcznika systemowego Debiana
(man) za pomocą jednolitego interfejsu. Jak widać jest to często spotykana
praktyka:
<a href="http://www.freebsd.org/cgi/man.cgi">FreeBSD</A>,
<a href="http://man.netbsd.org/">NetBSD</A>,
<a href="http://www.openbsd.org/cgi-bin/man.cgi">OpenBSD</A>,
<a href="http://docs.hp.com/hpux/os/man_pages.html">HP (HPUX)</A>,
<a href="http://publib16.boulder.ibm.com/cgi-bin/ds_form?lang=en_US&viewset=AIX">IBM (AIX)</a>,
<a href="http://techpubs.sgi.com/library/tpl/cgi-bin/init.cgi">SGI (Irix)</a>,
i
<a href="http://docs.sun.com/db?p=subj/manpages_solaris">Sun (Solaris)</a>.
Co ciekawe istnieje już kilka nieoficjalnych serwerów z całą bazą
podręcznika Debiana np. na stronach
<a href="http://www.fifi.org/cgi-bin/man2html">Fifi</a>.
Braku takiego centralnego repozytorium został zgłoszony jako błąd nr.
<a href="http://bugs.debian.org/264589">#264589</a>. Pierwsze próbne (wersje
Beta) tego serwisu są już dostępne pod adresem <a
href="http://manpages.debian.net/cgi-bin/search_man.cgi">manpages.debian.net</a>.
# Funny enough, no Linux distributions provides an official source
# for online search of manpages. Not even Red Hat does this.
# And TLDP points to different unofficial sources including
# http://linux.ctyme.com/
# jfs
<li>Implementacja URN. Pozwoli, to użytkownikom sprawdzać dokumentację
lokalnie, poprzez stronę www lub na serwerach lustrzanych. Lokalna konfiguracja
mogłaby być używana do wskazywania najbliższych (ewentualnie najdogodniejszych)
mirrorów, lub zarządzania. <tt>doc-base</tt> mógłby używać URN raczej
do wskazywania dokumentów niż używanych przez nich nazw plików.
<li>Wprowadzenie jednolitego formatu wynikowego dla dokumentacji dostępnej w
pakietach. Zgodnie z zasadami polityki debiana (debian-policy) pliki
dokumentacji powinny być w html. Zapewne część użytkowników chciałaby też
mieć wersję w PostScript czy zwykłym pliku tekstowym. Pewnym rozwiązaniem
byłoby załączanie w pakietach .deb _tylko_ dokumentów źródłowych SGML.
Dopiero po instalacji pakietu na żądanie (albo automatycznie po instalacji)
generowane byłyby pliki wynikowe w wybranych formatach.
Takie rozwiązanie ma kilka zalet:
<ul>
<li>zmniejszenie rozmiarów plików .deb
<li>lepsze dopasowanie do potrzeb użytkownika
<li>możliwość dostosowania odnośników podczas kompilowania dokumentacji,
np. wymiana odnośników internetowych na lokalne jeśli istniały by
odpowiednie pliki !!!
<li>utrzymywanie ogólnych indeksów stron aktualnymi (ala dwww) będzie prawdopodobnie prostsze
</ul>
oraz kilka niedogodności:
<ul>
<li>użytkownicy będą musieli posiadać zainstalowany debiandoc-sgml (nie jest to duży pakiet)
<li>formatowanie będzie trwać kilka sekund (nie jest to dużo, ale
zwykłe rozpakowanie trwa krócej)
</ul>
<p><tt>doc-base</tt> może określać podstawy systemu tego typu, ponieważ
śledzi metadane dokumentów.
<li>Przydałby się dowiedzieć, które z dokumentów są najczęściej używane
(lub poszukiwane) przez użytkowników. Dzięki takim informacją nasz zespół
mógłby się skupić na tych najważniejszych. Problem ten nie został jeszcze
szczegółowo zbadany. Źródłem informacji mogłyby być listy dyskusyjne
(przeprowadzić małe głosowanie), statystyki odwiedzin serwerów www (można
również wliczyć serwery lustrzane). Ponieważ część dokumentacji jest
dostarczana również w pakietach, można zrobić takie zestawienia na podstawie
danych zbieranych w popularity-contest.
<li>Utworzyć skrypty generujące informacje o dostępnych podręcznikach (man) i
wyświetlające odpowiednie informacje na stronach www. Można to uczynić
pobierając odpowiednie dane z <tt>manual.defs</tt> i <tt>version.defs</tt>
bezpośrednio przez CVS.
<li>Utworzyć system monitorowania stanu tłumaczeń korzystając ze stron CVS.
Rozważamy użycie infrastruktury, działającej obecnie przy pracach nad
podręcznikiem instalacyjnym.
<li>Monitorować czas ostatniej zmiany poszczególnych dokumentów. Dzięki temu
użytkownicy przeglądający dokumenty będą mogli ocenić czy poruszane tam
zagadnienia dotyczą posiadanego przez nich systemu.
<li>Rozważyć pracę nad dokumentacją dostępną w językach innych niż
angielski. W repozytorium CVS są już katalogi dla innych języków, w których
znajduje się dokumentacja stworzona w innych językach.
<li>Rozważyć udostępnienie interaktywnego mechanizmu dodawania notatek przez
czytelników dokumentacji. Można stworzyć serwis na zasadzie stron wiki
odseparowany od samej pierwotnej dokumentacji, albo połączony z tym co jest
obecnie. Zamieszczanie uwag przez użytkowników byłoby pomocna dla autorów
dokumentacji przy wprowadzaniu poprawek. Jak wiadomo podobne mechanizmy
dobrze sprawdzają się przy innych projektach dokumentacji (PHP).
<li>Umożliwić użytkownikom zgłaszanie błędów w dokumentacji poprzez system
śledzenia błędów. Część dokumentów (ta znajdująca się w pakietach) posiada
już taką możliwość. Ciekawym rozwiązaniem byłoby połączenie całej dostępnej
dokumentacji w ten sposób.
</ul>
|
