Emerald Editor Discussion
May 26, 2017, 12:47:49 am *
Welcome, Guest. Please login or register.
Did you miss your activation email?

Login with username, password and session length
News:
 
   Home   Help Search Login Register  
Pages: 1 [2] 3
  Print  
Author Topic: Documentation  (Read 27988 times)
0 Members and 1 Guest are viewing this topic.
Wraithan
Prospector
*
Posts: 9


« Reply #15 on: May 31, 2006, 12:46:47 am »

I prefer CHM help files, personlly only use PDFs for presentations to other companies because it can retain formating and images in a nice system, but I like to be able to search and what not like is available in chm (its the only way i learned PHP lol)
Logged
daemon
Developers
Gem Cutter
***
Posts: 107


WWW
« Reply #16 on: May 31, 2006, 01:56:44 am »

XSLT can also be used to transform into CHM. That's the beauty of it Tongue.
Logged
Arantor
Site Administrator
Administrator
Master Jeweller
*****
Posts: 618



« Reply #17 on: June 02, 2006, 12:49:31 pm »

I'm going to try and start putting something together for general documentation tonight in DocBook - I'm not going to start doing any programming documentation, just general documentation on Emerald Editor.
Logged

"Cleverly disguised as a responsible adult!"
JoBe
Guest
« Reply #18 on: June 03, 2006, 09:42:19 pm »

I may be too late and it may be a crude idea...
but a Wikit is the thing I always wanted to use if I had a searchable manual to write.
http://wiki.tcl.tk/1
http://www.equi4.com/wikit.html

My idea would be to have the manual as a seperate executable

A nice example for a wikit is this:
http://notebook.wjduquette.com/index.php?title=Main_Page

Thoughts on the wikit:
+ everyone could write the manual because no serious programming knowledge is necessary
+ easy to write, easy to search inside, easy to make links inside
- no CHM, pdf or other files possible AFAIK

Thoughts on the seperation between manual and editor executables:
+ Keeps the editor file size small
- Different download packages, with and without manual necessary
Logged
Arantor
Site Administrator
Administrator
Master Jeweller
*****
Posts: 618



« Reply #19 on: June 03, 2006, 10:03:57 pm »

I'm just having a look at Notebook at the moment to get some idea of exactly what you mean.

It seems a nice idea but it seems to bring the immediate issue that you then have to consider porting it to other platforms, or making it cross-platform from the ground up.

The general plan was to have the main executable available on its own, with the manual available online, or downloadable as HTML, CHM, PDF or even plain text.

I do agree that keeping the manual and other docs outside of the main distribution is a good idea, though (what does everyone else think?)

I'm still playing around with DocBook at the moment, btw.
Logged

"Cleverly disguised as a responsible adult!"
Zhrakkan
Official Mascot!
Beta Testers
Gem Cutter
***
Posts: 177



WWW
« Reply #20 on: June 04, 2006, 05:53:57 am »

I would imagine, the manual could be OUTSIDE the downloaded file.

Then when you goto HELP.
It can point you to the downloadable version, plus the online version
Logged

News Manager and Unofficial Mascot
Join the Emerald Editor Project - Message Me!
Emerald Editor - "A Jewel of an Editor"
-----by the way, that name is pronounced "Za-Rack-In"
JoBe
Guest
« Reply #21 on: June 04, 2006, 08:42:48 am »

A wikit is a starkit. A starkit must be started with a tclkit runtime.
These runtimes are available for Windows, Linux, Mac and a lot of other OSs. I used it mostly for windows and once for linux.
http://www.equi4.com/tkstarted.html
http://www.equi4.com/tclkit.html
http://tcltkaqua.sourceforge.net/

A starpack is a starkit wrapped into an executable with one of these tclkit runtimes.

The beauty of it is that you need only 5 files and no extensive programming knowledge to make a single file executable manual for Lin, Win & Mac. The 5 files are:

1. tclkit runtime for Linux
2. tclkit runtime for Mac
3. tclkit runtime for Windows
4. wikit.kit
5. sdx.kit - the wrapper

  • You start the wikit.kit with one of the runtimes and begin editing the wiki/manual. Save when you are finished and the manual is stored in a file called wikit.tkd
  • Unwrap the wikit.kit using a runtime and sdx and you get a folder with the virtual file system of the wikit.
  • In there you will find a file called wikidoc.tkd.  Replace this *tkd file with the one containing the manual and rename it to wikidoc.tkd
  • Wrap the virtual file system into an executable using sdx and a runtime.

That's all there is to do. Wrap it with different runtimes for different OSs.
I don't know if this is easier than any of the other methods already discussed. I am suggesting this because the Wikit is the only method I know other than a plain text manual or a html. The main reason for me to chose a wikit would be the ease of use, but this depends of course  on what you are used to.
Logged
daemon
Developers
Gem Cutter
***
Posts: 107


WWW
« Reply #22 on: June 04, 2006, 05:34:47 pm »

Learning Docbook is cake. It's just XML (thus has an HTML syntax) with some special tag keywords. I think it's the best option because it can be transformed to any output and is a commonly-recognized format that isn't tied to the world-wide-web.
Logged
Arantor
Site Administrator
Administrator
Master Jeweller
*****
Posts: 618



« Reply #23 on: June 04, 2006, 09:41:40 pm »

I think I've got the general hang of it now, but I have a slightly more fundamental problem...

Should the manual be a single DocBook file, or each chapter or section as separate DocBook files...?
Logged

"Cleverly disguised as a responsible adult!"
daemon
Developers
Gem Cutter
***
Posts: 107


WWW
« Reply #24 on: June 04, 2006, 10:19:17 pm »

I like doing one file per chapter.
Logged
Pvt_Ryan
Master Jeweller
******
Posts: 422



WWW
« Reply #25 on: January 16, 2007, 03:40:35 pm »

I think the docs should be in xml.

I am not a big fan of xml but i think for documentation it would be perfect.

something along the lines of

<id="0" />
<title></title>
<link></link>
<body>
<image="" />
<body>

then when parsed

-------------
FAQ
---

link1
link2
link3
---

title1

body1 with or with images
---

title2

body2 with or with images
----------------


The ID field would be used for the Documentation program ( a simple web page that updates the xml file)

tbh this would take any decent web programmer about 45secs to develop and write.

and it could be placed on the web for the devs to update as and when
Logged
Arantor
Site Administrator
Administrator
Master Jeweller
*****
Posts: 618



« Reply #26 on: January 16, 2007, 04:16:32 pm »

Well, I have been meaning to dig into the DocBook/XML stuff but haven't had the time lately. But I still wonder if DocBook at least is the right way to go?

I can see the benefits of it being in XML, but I'm also wondering if I shouldn't utilise some of the features of the forum - SimpleMachines, who wrote the forum, also provide their user manual using the same basic software. (If you're curious, try visiting http://docs.simplemachines.org/ then visit http://docs.simplemachines.org/?theme=1 - does the content look familiar?)

We're already using the forum software to manage parts of the website (i.e. the front page, About, FAQ, Team pages etc.) and it would be possible to write a script to pull the information out of the forum, as the framework already exists for that.

Basically, I'm trying to reuse existing software and existing frameworks without defining new standards or bringing in extras. Thoughts, anyone?
Logged

"Cleverly disguised as a responsible adult!"
Pvt_Ryan
Master Jeweller
******
Posts: 422



WWW
« Reply #27 on: January 16, 2007, 04:44:21 pm »

i dont mind developing / helping develop the documentation system as long as somebody else does the layout and css.

Note: although i said decent web dev above.. i am not one and sadly work does keep me quite busy..

so it may take me a few days or a week or 2.

let me know if you want me to
 
« Last Edit: January 16, 2007, 04:48:50 pm by Pvt_Ryan » Logged
Szandor
Senior Miner
***
Posts: 92



« Reply #28 on: January 16, 2007, 07:08:55 pm »

People will want to have the documentation downloadable and possibly printable, therefore I say we go for DocBook. We would probably only need the smaller version for our needs. Just like people have already stated, this would let us create websites, help files and PDF:s through XSLT.

As for the layout and CSS, that's what I do for a living so I could help out with that.
Logged

"Cleverly disguised as an original signature..."
per9000
Miner
**
Posts: 10



WWW
« Reply #29 on: March 06, 2007, 01:57:53 pm »

My experiences of docBook, Doxygene, XML etc.

I work coding a huge system in a multi-language (FORTRAN, C, C# etc) environment. We also produce documentation of the stuff for users.

Doxygen
I absolutely love Doxygen in combination with fx. C# for documenting the code. In C# the *same* documentation produces help-popups while typing (in Visual Studio and most likely in SharpDevelop) and html. This documentation can also produce xml, latex-code etc, etc. It's hard for me to see any other system producing all that outputs from the same source (on the other hand: I haven't tried all systems for documentation available). (I'll try to attach a screenshot to show what I mean.)

As I see it: any other system (or at least systems with documentation in one file, code in another file) will *always* have lags in the documentation. Having the documentation in the code is also a great motivation for commenting the code.

The only real trouble with doxygen as I see it is that documentation will look a little different if Emerald will be coded in a multi-language environment.

Having the documentation on-line in html/xhtml/text/yada-yada is excellent for searching and indexing. A pdf is typically slow to search.

docBook
I once tried to use docBook but didn't even manage to produce hello world. docBook for me is eternally banned.

wiki
I totally love the idea of wiki's - but as I see it wikis are not good for documenting code. A wiki for the faq, or something else could be great. (I have never really gotten into this kind of forum system.)

Download
Downloading documentation can be chm-files or html or pdf, if Doxygen is used.


Please note that these are my experiences - interpret them as such - I do not claim to be almighty in my knowledge (but sometimes I think so).

/Per

home http://www.pererikstrandberg.se/
blog: http://www.pererikstrandberg.se/blog/



* screenshot_documentation.png (18.12 KB, 432x342 - viewed 718 times.)
Logged
Pages: 1 [2] 3
  Print  
 
Jump to:  

Powered by MySQL Powered by PHP Powered by SMF 1.1.19 | SMF © 2013, Simple Machines Valid XHTML 1.0! Valid CSS!
Page created in 0.163 seconds with 18 queries.