Documentation?

anzenews · 2005-02-21 17:01:25

Hi!

Is there some documentation on how to setp Xinha?

I used htmlarea forums to find answers (like "how do you use your CSS stylesheet file?") but since it is down now (and I doubt it will be back again) it would really be nice to have better documentation. The existing is very incomplete and outdated (or so it seems to me - it might be just incomprehensible).

I am looking for something like 'Setup guide' - first a general overview of the system, then some more common settings and ways of doing things, and then maybe some details (but then again, one could look into JS code to figure that out).

It took me hours to get more htmlareas into page even though this wasn't my first encounter with HtmlArea (I used v2.03 before that) - way too much, especially now that I see the result. It is really simple once you know how.

Anze

gogo · 2005-02-21 22:32:12

There is no documentation at the moment, infact I've removed all the old documentation because I think it would create more confusion than anything.

The best way at the moment is to grab the nightly (use that it's more or less OK, there are some slight problems) and have a look at examples/full_example-body.html you can use that file as a boilerplate (just read through the source it explains how to use it to set up your own editors).

Any questions, post here. When you've got it worked out perhaps you would like to create a page in the Wiki to help others in the same situation - perhaps http://xinha.gogo.co.nz/NewbieGuide

anzenews · 2005-02-22 09:24:08

Actually, the link you have sent in the other post helps a lot... Thank you!

http://xinha.gogo.co.nz/cgi-bin/trac.cgi/wiki/Plugins

Apart from that, I am a bit new to htmlarea 3 / Xinha but I wouldn't mind spending some time writing documentation about it. The only problem is that there are many ways to skin a cat (htmlarea a textarea? ). There are many examples taking a different approach to things and some of them are probably legacy (deprecated). It would be nice to make a list of stuff that is 'officially supported' so that users know what to use - unfortunately I don't know htmlarea good enough to do that. I could, however, go through all documentation and assemble it in one big document. But someone (you?) who knows Xinha better should say what parts are deprecated, what parts are wrong and what is the Right Way (tm).

If I put together a list of documents, examples and similar, would you look at them and write comments? Then we could put it all in one (official?) place.
If it helps, I would be more than happy to do it.

I think good documentation is what this project lacks the most - if we want people to use this (which is the only way to get new developers) we must enable them to set this up without too much fuss.

Enjoy!

Anze

gogo · 2005-02-27 00:56:11

anzenews wrote:

If I put together a list of documents, examples and similar, would you look at them and write comments? Then we could put it all in one (official?) place.
If it helps, I would be more than happy to do it.

Yes certainly! The best thing to do is to start writing it in the Wiki, say at

http://xinha.gogo.co.nz/XinhaDocumentation

then it can be edited by anybody

anzenews · 2005-02-28 06:52:17

I am not that familiar with Wiki - but it looks nice and easy to use. I will look into it...

clem · 2005-03-07 08:25:39

Documentation, yes please.

I am currently contributing to the documentation for CMSimple www.cmsimple.dk and the the question of third party internal editors is a big one. The Author has provided htmlarea, fckeditor and tinymce and xinha has been mentioned in the forum. The problems are twofold- providing a Userguide for naive endusers which is fun- when the now 5 possible editors are all different (slightly to you arnd me- massively so to the computer illiterate).
-providing a installation guide for those who want to change the default editor. (that includes me!)

The ripple effect of a minor change can extend to 24 pages- though the major work will only be on one.
http://www.cmsimple.dk/?Help is the current help pages- but a major update is due in the next couple of weeks. It is rather recursive as CMSimple is being used as the vehicle to carry the documentation. It is possibly a better option than a wiki.

Experience tells me, that writing the retched documentation is far more complicated than coding- at least with coding the interpreter throws Warnings:- while with the documentation you are in a feedback whiteout.

If the current documentation is at examples/full_example-body.html could you post this as an anouncement on this forum!

Currently the documentation pages I am looking for are:
How to make my buttons appear on 4 lines not one superline (like it used to with htmlarea?)
How to make Undo and Redo work- it never did with htmlarea.
How to suppress chars such as '<' being converted into htmlentities- that blows the search and php eval function.
How to supress extra linebreaks being inserted in my code- that blows preg_replace
Then the usual stuff on adding buttons.
The usual stuff on using the sidepane buttonbars.

Thanks guys for creating this xinha_fork- and the qualities of the comments on the previous htmlarea forum.

gogo · 2005-03-07 12:20:09

clem wrote:

Experience tells me, that writing the retched documentation is far more complicated than coding- at least with coding the interpreter throws Warnings:- while with the documentation you are in a feedback whiteout.

Not more difficult, just different. I'm reluctant to write it myself as I'd rather have a non-programmer do it, in my experience the minute the programmer starts writing user documentation all you succed in doing is confusing the end user

If the current documentation is at examples/full_example-body.html could you post this as an anouncement on this forum!

That example (in the nightly, not in the release yet) is indeed the best place for you to learn how to implement Xinha.

How to make my buttons appear on 4 lines not one superline (like it used to with htmlarea?)

Judicious use of the 'linebreak' toolbar element, see htmlarea.js for example.

How to make Undo and Redo work- it never did with htmlarea.

These buttons have been added back into the default toolbar in the nightly, they may or may not work for you, please let us know (via a ticket) if they don't.

How to suppress chars such as '<' being converted into htmlentities- that blows the search and php eval function.

Don't understand what you mean here, if you are meaning that you are trying to enter things like <?php blah ?> actually in the wysiwyg editor (or in the source code), then you're out of luck, it's not possible. There is some desire for being able to insert (limited) php code in source mode with it being represented with dreamweaver style shields in design mode, but thats a ways off yet.

How to supress extra linebreaks being inserted in my code- that blows preg_replace

Please explain more fully.

Then the usual stuff on adding buttons.

There are comments in htmlarea.js which explain this for now.

   /* Example on how to add a custom button when you construct the HTMLArea: */
   
      var editor = new HTMLArea("your_text_area_id");
      var cfg = editor.config; // this is the default configuration
      cfg.btnList["my-hilite"] =
       [ function(editor) { editor.surroundHTML('<span style="background:yellow">', '</span>'); }, // action
         "Highlight selection", // tooltip
         "my_hilite.gif", // image
         false // disabled in text mode
       ];
      cfg.toolbar.push(["linebreak", "my-hilite"]); // add the new button to the toolbar

The usual stuff on using the sidepane buttonbars.

For now, the best bet is to see the Stylist plugin, but very basically you use the addPanel() method of the editor which returns a div element which you can put stuff in.

 
myPanelsDiv = editor.addPanel('right'); 
myPanelsDiv.innerHTML = 'This will appear in a panel on the right.';

and if you no longer want the panel

editor.removePanel(myPanelsDiv);

what you do inside the panel is entirely up to you.

akaEdge · 2005-03-08 06:32:35

Hi,

I too would be very happy to write (or help write) the documentation for Xinha. I have used HTMLArea for some time now - with various settings, and am pretty good at interpreting javascript.

I am currently switching over existing sites using HTMLArea r3 to Xinha and am taking notes as I do so. These basically detail exactly how I am implementing Xinha, and also have side-notes on what the differences between it and HTMLArea are. I would be very happy to post these notes as a thread, or even send them to someone who is already in the process of writing some documentation (anzenews?).

I think the best place for documentation is on the Xinha website on a page managed by one or two people - who keep a close eye on the forums!! Let me know if I can be of help here, and if not directly, where I might be able to send my notes for somone's reference.

akaEdge

clem · 2005-03-08 14:08:18

James:

Thanks for the rapid response, I was impressed. I have followed your advice and now have a php file written to configure xinha and a working editor. More than that a working editor that has all the features I need to write the documentation for CMSimple- my original goal.

OK- a bit shaky in parts-but now best of the bunch.

Some points.

The nightly release does not appear in zip format.

Buttons fixed using the magic "linebreak". I use the word magic with care!. I still don't understand how when I registerer the charmap plug it the icon found its way next to <hr> when it is not mentioned in my config.toolbar!

Undo Redo work fine now- a config problem.

One of the features of CMSimple is its ability to include scripting in its content pages.

http://www.cmsimple.dk/?Installer%27s_M … _Scripting

One of the features of documentation is the need to demonstrate these features, and also display the required source code. We would want the user to be able to cut and paste from the manual page into his live document and activate the code. At the moment the best way to fool the parser is to wrap a <-font size=2> <-/font> pair around each of the hash symbols. The user then removes these using the inline editor.

There are two requirements.
Both the hash symbols must be on the same line or preg_replace refuses to make a match and replace them with the <-?php eval (" xxxx ";): ?-> code. Some of the lines will be very long.

There must be a way to use php symbols within this area.

A common problem is that external editors helpfully insert htmlentities and line breaks into all the page not just the line that is being edited. As you can imagine this causes newbies problems and some of the old hands to have blood pressure problems!
I see there is a plug in to remove MSthingies- perhaps that is a way forward- or does it exist already?

As this thread is about documentation and not creating documentation for 3rd party software- back on thread.--
I fully accept that the information is there but I needed the clues you gave me last night to know where to start. Another example file is perhaps needed newbies_start_here.html. That gathers together the comment statements- with useful lines like
/-/ insert point one- insert your plugins here with HTMLArea.loadPlugin();
/-/ example---- HTMLArea.loadPlugin("CharacterMap");
It is a bit disconcerting to see so many references to HtmlareaEditor in the source code and examples perhaps these could be changed to Htmlarea/Xinha- to show that this code is current and not just legacy code that has been left in by mistake. (Also it give distance betwwen the product and javascript commands.

If anyone wants to see how we are using xinha with cmsimple- I'll glady zip together a package with relevant files.

Clem.

gogo · 2005-03-10 02:02:49

clem wrote:

The nightly release does not appear in zip format.

Thats fixed now.

Buttons fixed using the magic "linebreak". I use the word magic with care!. I still don't understand how when I registerer the charmap plug it the icon found its way next to <hr> when it is not mentioned in my config.toolbar!

The plugin pushes the button into the toolbar. That whole area needs to be looked at again as it's not the best way in terms of configurability.

One of the features of CMSimple is its ability to include scripting in its content pages.
http://www.cmsimple.dk/?Installer%27s_M … _Scripting

Yes I see, so the users would switch to html mode ("source view") and enter these tags. Well, as I say, currently it's not possible, the editor can only deal with valid well formed HTML, that's just the way these editors (that use the browser's API for editing) work, can't be changed (short of editing the browser source code!)

What has been requested is a way to allow showing the "server code" in source view, then transforming it to something embedded in a little "shield" image's alt tag in WYSIWYG view, and of course transforming back to the server code when you click submit.

This is all well and good, but it won't happen soon (unless somebody else cares to write the plugin, it wouldn't be hard I just don't have time right now), and it will ONLY work for simple server markup, it won't be possible to do something like...

<table>
<?php foreach($blah as $foo) { ?>
<tr>
<td><?php echo $foo ?></td>
</tr>
<?php } ?>
</table>

because there is no way to transform that into valid HTML to display in WYSIWYG mode, if we tried it would turn into something like...

<table>
<img src="php.gif" alt="foreach($blah as $foo) {" />
<tr>
<td><img src="php.gif" alt="echo $foo;" /></td>
</tr>
<img src="php.gif" alt="}" />
</table>

which is obviously invalid and the browser wouldn't have a clue how to render it.

It is a bit disconcerting to see so many references to HtmlareaEditor in the source code and examples perhaps these could be changed to Htmlarea/Xinha- to show that this code is current and not just legacy code that has been left in by mistake. (Also it give distance betwwen the product and javascript commands.

Yes, bugs take priority over branding though :) Changing the internal object names will make us incompatable to HTMLArea, which I would like to avoid until Xinha v1.0 is out really.

anzenews · 2005-03-10 05:10:07

akaEdge wrote:

Hi,
I am currently switching over existing sites using HTMLArea r3 to Xinha and am taking notes as I do so. These basically detail exactly how I am implementing Xinha, and also have side-notes on what the differences between it and HTMLArea are. I would be very happy to post these notes as a thread, or even send them to someone who is already in the process of writing some documentation (anzenews?).

I started writing documentation (getting existing documentation and changing it) but I found out I don't know enough about Xinha yet to finish the task. I figure once I get a working Xinha system together I will put the revised docs on the page. Now I simply don't know which parts of documentation work and which don't.
I would definitely be interested in your notes - but can't promise to put together documentation in less than 2 or 3 weeks (I'm leaving today on vacation for a week).

But do post it please! The more the better.

Anze

akaEdge · 2005-03-10 09:43:33

Thanks to gogo giving me Wiki access I have made a Newbie Guide at http://xinha.gogo.co.nz/cgi-bin/trac.cg … ewbieGuide and also a new thread for questions/amendments to it at http://xinha.gogo.co.nz/punbb/viewtopic … d=255#p255

I will look to start getting some documentation up and running in the next few days - hopefully with some kind of scalable structure that we can all add to as needed. I guess I am a believer in having something up there asap - it might not be complete but it should really help to get people started.

akaEdge

clem · 2005-03-12 16:16:59

James.

Cheers for the nightly zip.
Yes what I want is 'shielded code'- but I am not focused enough in JS and HTML to understand all the intricacies and pitfalls.
I don't have a problem with class or object names being called 'htmlarea'- but an hour or two on the inline comments- after a few beers may remove a few references to interactivetools.com.

Akaedge

The great task has started.
Can I put in a plea for howtos not man pages. ie. 'How do I add a button?' rather than 'Methods of toolbar.object' (if there is one?).
It needs to be aimed at the software installer who has blagged on his cv that he is fluent in js and php while actually only knows that there is a book on them both down at Waterstones!

Clem

akaEdge · 2005-03-13 05:19:26

- no worries Clem we'll do our best! Waterstones eh? very cunning - I think I should add some more things to my CV, I've seen loads of books down there!

gogo · 2005-03-19 00:31:39

clem wrote:

Yes what I want is 'shielded code'- but I am not focused enough in JS and HTML to understand all the intricacies and pitfalls.

I think we have a ticket for that as an enhancement. It's certainly on the cards.

Xinha Discussion Forum

Announcement

#1 2005-02-21 17:01:25

Documentation?

#2 2005-02-21 22:32:12

Re: Documentation?

#3 2005-02-22 09:24:08

Re: Documentation?

#4 2005-02-27 00:56:11

Re: Documentation?

#5 2005-02-28 06:52:17

Re: Documentation?

#6 2005-03-07 08:25:39

Re: Documentation?

#7 2005-03-07 12:20:09

Re: Documentation?

#8 2005-03-08 06:32:35

Re: Documentation?

#9 2005-03-08 14:08:18

Re: Documentation?

#10 2005-03-10 02:02:49

Re: Documentation?

#11 2005-03-10 05:10:07

Re: Documentation?

#12 2005-03-10 09:43:33

Re: Documentation?

#13 2005-03-12 16:16:59

Re: Documentation?

#14 2005-03-13 05:19:26

Re: Documentation?

#15 2005-03-19 00:31:39

Re: Documentation?

Board footer