Hi Richard, Am Donnerstag, 29. M?rz 2007 18:52 schrieb techno_plume-coding at yahoo.com: > > A diff against KPatience index.docbook from trunk is attached for > review. > Thanks a lot.
[snip] > d) Credits on the 1st page were getting a little long. So I moved some > to just the Contributors section. Hope this is okay? > I aggree, but may be Phil has an objection? > == Things I am unsure of == > > 1) This app also has a manpage, in the repository. Is there a policy > user apps should have a manpage? Are these written by hand typically > (or with something like Manedit), or somehow generated automatically > from Docbook files through the autoconf/cmake scripts? Or by XSLT? I'm > wondering if I should make a separate diff for the app's manpage, when > amending a docbook manual. > There are a lot of *man.docbooks in the documentation (and I have translated many to german), but I think they are useless, as they are not visible in khelpcenter and not visible as man pages. Maybe Phil knows more? > 2) Marked up a reference to a feature, like so: > - especially if you use the undo feature > + especially if you use the <guibutton>Undo</guibutton> feature > > In this case, the 'Undo' option is accessible through *both* the > toolbar button - and - the edit menu. I wasn't sure which I should > choose. When referring to a something like this, is that the correct > markup? Previously there were no markup tags around that option. > I think there is no rule to use guimenuitem or guibutton, but a lot of markup (guibutton, guimenu, guisubmenu, guimenuiten, guilabel etc) makes it easy for me to detect possible errors in the documentation with my scripts. > 3) Removed a section that read "Use of the menu is too easy to be > described now.". > I felt if it isn't described, there isn't much point in telling the > user it wasn't going to be. :) > Also, I later added a set of chapter tags, because that removal made it > go from listing terminology to rules of Klondike, on the same page. > > _Is_ this appropriate, or should the menu options really be described? > If so, Phil R., you mentioned on a kbackgammon bug that you had a > script that might make writing menu refs easier. Perhaps I could save > some time using that, if I need to document the menu? > Better to describe the tasks and behaviour of the application than to write a menu desciption for this simple gui. > 4) Since the doc (if approved+committed) is going into /trunk, should I > change down the revisionnumber in the file to match the application > version in KDE 3.5.5 ? > I will do that. > 5) Adding newish contributor entities cause the XML check to choke. > This is because they weren't present in KDE3. Say I add myself to the > contribs section. Should I add the entity for myself, or just put my > name and email address in manually to later be switched with the > entity? > To use a contributors entity it has to be added to kdelibs/kdoctools//customization/entities/contributor.entities to make meinproc happy. Putting in your name and email address in manually works without this, it can be later changed to an entity. Burkhard L?ck
