Discussion:
HTML Help
(too old to reply)
Oliver Giesen
2004-05-24 13:05:57 UTC
Permalink
Jerzy,

I saw that you have begun to add HTMLHelp support to WinCvs as well as a
dummy(?) help project. Just so we do not duplicate efforts, I'm not sure
if you might have missed from discussion on the CVSGUI list that I have
recently started to write a new help file from scratch. The document is
still in a very early stage but I'm still confident that I could
eventually complete it. My plan so far was to first finish description
of the command dialogs and related UI elements before I published what I
have. My current estimate is that I could reach that point in about one
or two months.

Time is really limited for me at the moment as we're moving out and have
to clear the old flat by the end of the week. In the same context I also
haven't been able to do any work worth of note on the help file for the
last two weeks or so.

Anyway, if you approve of the direction I've already started to take
I'll gladly transfer what I have to the CVSGUI repository right now.
Some time ago I uploaded a snapshot of what I had to my site. It's still
there:

Browsable online: http://people.freenet.de/ogiesen/WinCvsHelp/

CHM download: http://people.freenet.de/ogiesen/WinCvsHelp/WinCvs.chm

That snapshot is however a bit out of date already. I'll try to upload
the current state of affairs tonight. Currently the only real content is
in the "Commands" and "Preferences" chapters of the "The WinCvs User
Interface" section (nowhere near complete - the Annotate or Branch
topics are about as good as it gets in that version of the document, by
now I have added a few more commands and Glossary entries and fixed some
texts).

Let me know what you think.

Cheers,

Oliver
---- ------------------
JID: ***@jabber.org
ICQ: 18777742 (http://wwp.icq.com/18777742)



------------------------ Yahoo! Groups Sponsor ---------------------~-->
Make a clean sweep of pop-up ads. Yahoo! Companion Toolbar.
Now with Pop-Up Blocker. Get it for free!
http://us.click.yahoo.com/L5YrjA/eSIIAA/yQLSAA/NhFolB/TM
---------------------------------------------------------------------~->


Yahoo! Groups Links

<*> To visit your group on the web, go to:
http://groups.yahoo.com/group/cvsgui-dev/

<*> To unsubscribe from this group, send an email to:
cvsgui-dev-***@yahoogroups.com

<*> Your use of Yahoo! Groups is subject to:
http://docs.yahoo.com/info/terms/
kaczoroj
2004-05-24 16:17:29 UTC
Permalink
Oliver,
Post by Oliver Giesen
I saw that you have begun to add HTMLHelp support to WinCvs
as well as a dummy(?) help project.
Yeah, it was about time ;)

It's actually operational already, at least from the technical point
of view, and the project is simply a converted
freshly-created WinHelp project. I decided that the current WinCvs
help is not worth converting and it's better to start a new.

I need to rename the generated files and do a cleanup as well as
complete HTML help framework code - particularly dialogs.
Post by Oliver Giesen
Just so we do not duplicate efforts, I'm not sure if you might have
missed from discussion on the CVSGUI list that I have recently
started to write a new help file from scratch.
I've seen that and it's good to have someone to write the real
contents while I will be plugging the nuts and bolts for the whole
thing to work.

What I will do now is to simply create the files for each dialog and
connect these so they popup as appropriate. Then I can start to fill
the real help text into it and your help will be very helpfull ;)

I can just as well use the bits you've got and put them into place if
I see the right fit.

I will announce here when it's all ready for others to start hacking,
for now expect the help files to be very volatile.

You can upload the latest version of your help files into SF patches
area and I will pick it up and try to arrange it before others so at
least some parts will be in it's correct place and the project won't
look so "dummy" ;)

Best Regards,
Jerzy





Yahoo! Groups Links

<*> To visit your group on the web, go to:
http://groups.yahoo.com/group/cvsgui-dev/

<*> To unsubscribe from this group, send an email to:
cvsgui-dev-***@yahoogroups.com

<*> Your use of Yahoo! Groups is subject to:
http://docs.yahoo.com/info/terms/
Oliver Giesen
2004-05-25 08:30:39 UTC
Permalink
Post by kaczoroj
Post by Oliver Giesen
Just so we do not duplicate efforts, I'm not sure if you might have
missed from discussion on the CVSGUI list that I have recently
started to write a new help file from scratch.
I've seen that and it's good to have someone to write the real
contents while I will be plugging the nuts and bolts for the whole
thing to work.
What I will do now is to simply create the files for each dialog and
connect these so they popup as appropriate. Then I can start to fill
the real help text into it and your help will be very helpfull ;)
I can just as well use the bits you've got and put them into place if
I see the right fit.
Hmm, that's not exactly how I imagined to tackle this... I'm currently
making really heavy use of cross-linking between topics and randomly
picking individual files out of that is not going to be very productive
IMO, especially if you're going to change the file names. If you could
tell me how you're implementing the link between framework and help
files I could possibly adapt my current project as a whole to it, e.g.
if I should use special anchors or file name conventions, etc.

When I added context-sensitive HTMLHelp support to one of our own apps.
I simply associated each dialog with an explicit URL (in contrast to
something auto-generated from the dialog resources or whatever) inside
the help file and each control on those dialogs worthy of documentation
with an anchor inside that associated file (still allowing an individual
override for links to other URLs as well). This way our documentation
writer could pretty much just hack away without caring about the
implementation details in the app while I kept the links up-to-date.
Post by kaczoroj
You can upload the latest version of your help files into SF patches
area and I will pick it up and try to arrange it before others so at
least some parts will be in it's correct place and the project won't
look so "dummy" ;)
For now I have updated the files at the link I supplied.

Cheers,

Oliver
---- ------------------
JID: ***@jabber.org
ICQ: 18777742 (http://wwp.icq.com/18777742)




------------------------ Yahoo! Groups Sponsor --------------------~-->
Make a clean sweep of pop-up ads. Yahoo! Companion Toolbar.
Now with Pop-Up Blocker. Get it for free!
http://us.click.yahoo.com/L5YrjA/eSIIAA/yQLSAA/NhFolB/TM
--------------------------------------------------------------------~->


Yahoo! Groups Links

<*> To visit your group on the web, go to:
http://groups.yahoo.com/group/cvsgui-dev/

<*> To unsubscribe from this group, send an email to:
cvsgui-dev-***@yahoogroups.com

<*> Your use of Yahoo! Groups is subject to:
http://docs.yahoo.com/info/terms/
kaczoroj
2004-05-25 11:42:10 UTC
Permalink
Oliver,
Post by Oliver Giesen
Hmm, that's not exactly how I imagined to tackle this...
Please note that I am not yet fully done with the framework itself. It
will all get cleared up as I will complete the transition...

To put things straight I am not planning to spent too much time on
writing help. I want it simple and usefull at the same time. Less
bloat more meat ;)

I also don't want to focus on CVS operations themself. I think we can
utilize the fact that CVSNT now comes with it's own help file and just
link to that or even the webpage.

I don't want to make a screenshots of each dialog and explain all the
options one by one because there is a much better and simpler way to
do this - help popups activated by a "?" button on the title bar of
each dialogs. A couple of lines of text can easily explain what each
option does. User doesn't have to and doesn't want to see the
screenshots in the help files because he can simply see the real
thing, the dialog itself. Instead, the dialog's help, as I see it,
explains in generic terms as to what the dialog is doing, some tricks
and FAQs. That is much easier to maintain and keep consistant.

I also want to have a simple, one-to-one mapping for dialog's help
files. It really helps when it comes to updating and maintaining the
files afterwards.
Post by Oliver Giesen
I simply associated each dialog with an explicit URL (in contrast
to something auto-generated from the dialog resources or whatever)
inside the help file and each control on those dialogs worthy of
documentation with an anchor inside that associated file (still
allowing an individual override for links to other URLs as well).
This is the same thing. In the HTML project file you create aliases
that link to whatever location in the help. The auto-generated part
just makes job easier because it allows to use symbolic names simliar
to the ones used in the code for that mapping. The files function
should be obvious from the name while the mapping makes it clear where
the files are used.

I am not sure what you mean by "override" here...?
Post by Oliver Giesen
This way our documentation writer could pretty much just hack away
without caring about the implementation details in the app while
I kept the links up-to-date.
You can still create documentation separately, e.g. the writer doesn't
care where I link his files from. But it helps to keep documentation
close to the software structure, particularly in our case.
Post by Oliver Giesen
For now I have updated the files at the link I supplied.
What about the .hhp and other project files? Can you zip all files as
they are and upload that too?

Best Regards,
Jerzy



------------------------ Yahoo! Groups Sponsor --------------------~-->
Yahoo! Domains - Claim yours for only $14.70
http://us.click.yahoo.com/Z1wmxD/DREIAA/yQLSAA/NhFolB/TM
--------------------------------------------------------------------~->


Yahoo! Groups Links

<*> To visit your group on the web, go to:
http://groups.yahoo.com/group/cvsgui-dev/

<*> To unsubscribe from this group, send an email to:
cvsgui-dev-***@yahoogroups.com

<*> Your use of Yahoo! Groups is subject to:
http://docs.yahoo.com/info/terms/
Oliver Giesen
2004-05-25 13:13:49 UTC
Permalink
Post by kaczoroj
I also don't want to focus on CVS operations themself. I think we can
utilize the fact that CVSNT now comes with it's own help file
and just link to that or even the webpage.
Well, yes but it's basically still the same old Cederqvist with some
CVSNT enhancements added that has already been intimidating novice users
for ages... anyway, this touches another issue I already had on my
todo-list ever since I started documenting the current GUI:

I think the GUI could do with a concerted effort to make captions,
labels and hint texts: A. consistent throughout all dialogs and menus
(e.g. there are at least three different captions for "do not recurse"
options) and B. consistent with the corresponding descriptions of
options in the commandline client (i.e. cvs -H output) where applicable.
The latter would be even more important if you were planning to simply
link the dialogs to the CVSNT manual.
Post by kaczoroj
I don't want to make a screenshots of each dialog and explain all the
options one by one because there is a much better and simpler way to
do this - help popups activated by a "?" button on the title bar of
each dialogs. A couple of lines of text can easily explain what each
option does.
There's only so much information you could put into those popups. I see
the strength of a full-blown help file here in being able to inject
notes, hints and tips and cross-links to related topics, e.g. notes
about common mistakes or alternative ways of doing something.

In any case I definitely have troubles imagining how you would be able
to pull anything useful out of the documents I created so far if that is
what you're after... well, the option descriptions _are_ there but they
only make up a tiny fraction of what I'm doing or about to do...

I just don't want to put all that effort into producing a full-blown
XHTML-compliant documentation project with Glossary, Index, Related
topics links, Basic Concepts chapters and nice stylesheets if all that's
going to happen to it in the end is that individual option description
texts get copy&pasted into tiny popups... now I know this is not what
you have in mind but I think you get the point of my concern. I wanted
to produce something that novice users would not just clap shut again
right after having taken a quick look at it as I think is the case with
most CVS documentation currently out there...
Post by kaczoroj
User doesn't have to and doesn't want to see the
screenshots in the help files because he can simply see the real
thing, the dialog itself.
In fact that's contrary to our observations, even though I must admit
that these observations probably do not apply to the majority of
developers. We're targetting a far less tech-savvy audience. Problem is
most of those people are uncomfortable with having multiple windows
visible at the same time (in this case the application and the help
file). Personally, whenever I have to work on a single monitor setup
below 19" I tend to feel the same. Clickable screenshots inside the help
files IMO put all the information readily available back in one neatly
organized window...
Post by kaczoroj
Instead, the dialog's help, as I see it,
explains in generic terms as to what the dialog is doing, some tricks
and FAQs.
OK, that's a lot closer to what I have been doing. Definitely the road
to consensus... ;)
Post by kaczoroj
I also want to have a simple, one-to-one mapping for dialog's help
files. It really helps when it comes to updating and maintaining the
files afterwards.
Depends. Maybe I'm misunderstanding you but if you mean that each
helpfile should be self-contained, i.e. without any cross-links that
could potentially become invalid, this would mean you have to explain
things like the Module or Tag browser or CVSROOT wizard or history
combos or the semantics of revision identifiers or modules, just to name
a few, all over again for each and every dialog that uses them. That is
an awful lot of duplicated content that has to be kept in sync... I
prefer just keeping the links valid. It's easy to do with the right
tools.
Post by kaczoroj
Post by Oliver Giesen
I simply associated each dialog with an explicit URL (in contrast
to something auto-generated from the dialog resources or whatever)
inside the help file and each control on those dialogs worthy of
documentation with an anchor inside that associated file (still
allowing an individual override for links to other URLs as well).
This is the same thing. In the HTML project file you create aliases
that link to whatever location in the help.
Ah, OK. I wasn't aware of aliasing so far. Will have a look at it.
Post by kaczoroj
The auto-generated part
just makes job easier because it allows to use symbolic names simliar
to the ones used in the code for that mapping. The files function
should be obvious from the name while the mapping makes it
clear where the files are used.
OK. I'll have a deeper look into the implementation then. Didn't have
much time for it so far. Will probably have to wait until next week...
Post by kaczoroj
I am not sure what you mean by "override" here...?
In our case I associated every dialog with exactly one topic file inside
the help file. Control help by default only links to anchors inside that
very document. Sometimes however it is necessary to link to (an anchor
in) a different document, e.g. because it is a common control that is
used on a lot of other dialogs or simply because the explanation in
question is too verbose to include in the main file for that dialog. I
needed to make sure that that was still possible.
Post by kaczoroj
You can still create documentation separately, e.g. the
writer doesn't
care where I link his files from. But it helps to keep documentation
close to the software structure, particularly in our case.
I think I am fulfilling at least that requirement with what I've been
doing so far. Just not to the point where I actually named files and
anchors after identifiers used in the code. You could probably say, I am
currently keeping close to the "outside" structure of the software.
Post by kaczoroj
What about the .hhp and other project files?
Actually they are already there if you know where to look. They're right
next to the .chm file with corresponding .hhp/.hhc/.hhk extensions.
Post by kaczoroj
Can you zip all files as
they are and upload that too?
Will probably do that tonight.

Cheers,

Oliver
---- ------------------
JID: ***@jabber.org
ICQ: 18777742 (http://wwp.icq.com/18777742)



------------------------ Yahoo! Groups Sponsor --------------------~-->
Yahoo! Domains - Claim yours for only $14.70
http://us.click.yahoo.com/Z1wmxD/DREIAA/yQLSAA/NhFolB/TM
--------------------------------------------------------------------~->


Yahoo! Groups Links

<*> To visit your group on the web, go to:
http://groups.yahoo.com/group/cvsgui-dev/

<*> To unsubscribe from this group, send an email to:
cvsgui-dev-***@yahoogroups.com

<*> Your use of Yahoo! Groups is subject to:
http://docs.yahoo.com/info/terms/
Oliver Giesen
2004-05-25 22:50:58 UTC
Permalink
Post by Oliver Giesen
Post by kaczoroj
Can you zip all files as
they are and upload that too?
Will probably do that tonight.
The latest snapshot is now at:

http://people.freenet.de/ogiesen/WinCvsHelp.zip

Note again that I don't consider any single topic of this completed so far.
It is in pre-pre-Alpha state and _will_ change considerably. I only uploaded
this for review and to illustrate the general direction I was taking. I
don't think it's any good for anything else yet...

Cheers,

Oliver
---- ------------------
JID: ***@jabber.org
ICQ: 18777742 (http://wwp.icq.com/18777742)



------------------------ Yahoo! Groups Sponsor --------------------~-->
Yahoo! Domains - Claim yours for only $14.70
http://us.click.yahoo.com/Z1wmxD/DREIAA/yQLSAA/NhFolB/TM
--------------------------------------------------------------------~->


Yahoo! Groups Links

<*> To visit your group on the web, go to:
http://groups.yahoo.com/group/cvsgui-dev/

<*> To unsubscribe from this group, send an email to:
cvsgui-dev-***@yahoogroups.com

<*> Your use of Yahoo! Groups is subject to:
http://docs.yahoo.com/info/terms/
kaczoroj
2004-05-26 09:41:07 UTC
Permalink
Oliver,
Post by Oliver Giesen
Well, yes but it's basically still the same old Cederqvist
with some CVSNT enhancements added that has already been
intimidating novice users for ages...
We don't need it in WinCvs help. I will provide the menu to CVS help
back again, but this time it will search and launch the cvs.chm that
comes with CVSNT, as per "Alternate CVS" settings.
Post by Oliver Giesen
I think the GUI could do with a concerted effort to make
captions, labels and hint texts: A. consistent throughout
all dialogs and menus (e.g. there are at least three
different captions for "do not recurse" options) and B.
consistent with the corresponding descriptions of options
in the commandline client (i.e. cvs -H output) where applicable.
Sure. And making those help popups will be the perfect time to do
that, together with using the same resource ID for similiar controls..
.
Post by Oliver Giesen
There's only so much information you could put into those popups.
I see the strength of a full-blown help file here in being able
to inject notes, hints and tips and cross-links to related
topics, e.g. notes about common mistakes or alternative ways
of doing something.
You can put quite a lot. Try to click the question mark cursor on the
on various controls in the standard color selection dialog. Some of
these popups go to ver 10 lines of text and explain quite a lot about
color selection.

The additional help can be easily provided in the full help text for a
dialog. I just don't see the point in duplicating the images that the
user can see anyway. Not to mention those take a lot of space and it's
going to be outdated pretty soon. No screenshots, please!

Actually there are times where screenshots can be usefull. A toolbars
might be one example. Still, these are rather small and quite
different from having full sized dialogs in your help files...
Post by Oliver Giesen
In any case I definitely have troubles imagining how you would
be able to pull anything useful out of the documents I created
so far if that is what you're after... well, the option
descriptions _are_ there but they only make up a tiny fraction
of what I'm doing or about to do...
I am after checking it out and seeing where and how to put it in so it
works good with what I am doing.
Post by Oliver Giesen
I just don't want to put all that effort into producing a
full-blown XHTML-compliant documentation project with Glossary,
Index, Related topics links, Basic Concepts chapters and
nice stylesheets if all that's going to happen to it in the end
is that individual option description texts get copy&pasted into
tiny popups...
Not to worry. Apart from a controls and dialogs related topics there
is a lot of room for general help on other subjects. It's just at the
moment I want to have the GUI linking and calling into help properly.
Some of that overlaps with your work, some doesn't.
Post by Oliver Giesen
now I know this is not what you have in mind but I think you get
the point of my concern. I wanted to produce something that novice
users would not just clap shut again right after having taken a
quick look at it as I think is the case with most CVS
documentation currently out there...
This is actually the case with most of *any* documentation out there ;
)

Trying to put my (a bit incomplete) vision at the moment I see three
different subjects here:

1. Help about controls on the dialogs (buttons, checkboxes etc.)
2. Help aboout dialogs/commands/operations (commit, update...)
3. General WinCvs/CVS help.

I want to make controls related help as a popups rather than a
screenshots with all options described. It's simple to make, simple to
maintain and saves a lot of space.

The dialogs/commands help is best done as separated pages,
cross-linked as needed (e.g. Checkout dialog naturally linking to the
Tag and Modules browsers, CVSROOT wizard etc.). Large GUI, shared
elements will have their own pages - dialogs CVSROOT wizard or
funtional blocks like "message entry" that is same for commit, import
and other dialogs. In general, no screenshots here either unless it's
reasonable. For example it's OK to have a screenshot showing the
modules combo box with the ellipsis button to invoke browser, or the
message editing group of controls.

The general CVS help will be left to CVSNT manual which we will link
to from the help menu.

The general WinCvs help is where most of your work will come into
play.

It's also possible we will interlink or even reuse the same files in
any of the help type if it's appropriate.
Post by Oliver Giesen
Depends. Maybe I'm misunderstanding you but if you mean that
each helpfile should be self-contained
It should be clear by now that's not the case. We gonna link it all
over the place...
Post by Oliver Giesen
Note again that I don't consider any single topic of this
completed so far.
I want to have it organized and checked in if you don't mind. That way
we can work together and cooperate. I want to get the help files into
their approximate final place and names so it is technically working.
I think I need one or two weeks to iron out the code-behind and link
it properly to the help files. Then we can fill in the empty spaces.
Then you can keep adding the general help topics as you see fit.

Best Regards,
Jerzy




------------------------ Yahoo! Groups Sponsor --------------------~-->
Make a clean sweep of pop-up ads. Yahoo! Companion Toolbar.
Now with Pop-Up Blocker. Get it for free!
http://us.click.yahoo.com/L5YrjA/eSIIAA/yQLSAA/NhFolB/TM
--------------------------------------------------------------------~->


Yahoo! Groups Links

<*> To visit your group on the web, go to:
http://groups.yahoo.com/group/cvsgui-dev/

<*> To unsubscribe from this group, send an email to:
cvsgui-dev-***@yahoogroups.com

<*> Your use of Yahoo! Groups is subject to:
http://docs.yahoo.com/info/terms/

Loading...