Documentation-manual-editor

From TYPO3Wiki

Teams  R&D-Committee	This page belongs to DocTeam (Members|Contact). see our current activities
Support for good documentation is our mission.

List Projects	The Documentation-manual - editor-project list pages	See Current Project Members, Wishlist
		you can help if you like!

Contents 1 Our aim 1.1 Current State 2 TYPO3 solution 2.1 Version 2.2 UTF-8 2.3 DB 2.4 Rights Management 2.5 OpenOffice preview when importing or exporting 2.6 iGoogle-like Widgets for the startpage 2.6.1 Startpage 2.7 RTE Code-Highlighting 2.8 Content Tagging 2.9 Translation - Spell check 3 Projects 4 Tool-comparison Screenshots 5 Tool-comparison table 6 Current Project Members 7 Wishlist

Our aim

We need a better way to work on manuals. OpenOffice alone doesn't allow to work as team on a manual, the wiki is not the best tool to work on a manual. We need a good solution for all documentation-authors and contributors.

This project is about comparing several solutions, working on proof-of-concept-implementations, creating the best solution as result.

Current State

Note	State: GoogleDocs and O3Spaces are tested well, now we're testing pipeline and pageflow. DocTeam - Virgil and Daniel 29 March 2008 (CET)

• 2008-04-24: First manuals (ajaxportal-Gadget "t3manual"): pear, typo3tut, subversion_diff_patch
• 2008-03-29: Updated Documentation for UTF-8_support
• 2008-03-22: Started installation of pipeline and pageflow based on mysql in UTF-8
• 2008-03-13: Started in mailinglist-dicussion english-list

TYPO3 solution

We want to find out, if we can use TYPO3 for everything - write tutorials, publish them, and check what need updates. If we move to TYPO3, then we also have to transfer the whole wiki to TYPO3. With all the linking.

We try the RTE as manual-editor and look for import/export - methods sxw/ PDF/ odt (=ODF).

Version

• 4.2 beta - to help with bug-solving

UTF-8

• use UTF-8
• check if an extension we want to use has problems with the string-length (use t3lib_cs instead of strlen)

DB

• READY UTF-8_support for translation also for symbolic-charsets japanese, russian, chinese

Rights Management

• be_acl must be very fine granular
• maybe kb_tsconfig_cond

OpenOffice preview when importing or exporting

• bitsoffice - an idea is to have two iframes to check if the import was successfull

iGoogle-like Widgets for the startpage

Startpage

Compare with Dashboard what is for the BE. -- Can we share some components?

• Extension ajaxportal

Mix:

• well-structured portal
• with iGoogle-like Widgets

So a beginner can have beginner-tutorials on this page, a core-developer can have the links to all important manuals there, a japanese translator can have the list of all japanese manuals and a japese tag-cloud. And everybody can "publish" his own startpage-configuration.

Isn't that great? It just needs the right JavaScript-Framework, TYPO3 and a nice architecture.

RTE Code-Highlighting

geshi SyntaxHighlighting for PHP-Scripts and TypoScript by CodeBox (sk_codebox) (contact: steffenk): Steffen Kamper can help to integrate this into RTE.

--Daniel Brüßler 14:11, 25 March 2008 (CET)

We currently develop the geshi highlight file for Typoscript. Also we have a new extension based on my sk_codebox which will be available soon and can be tested/observed here: http://forge.typo3.org/projects/show/extension-syntaxhighlight

--steffenk 19:16, 13 July 2008 (CEST)

Content Tagging

• categories (categories) (contact: madsbrunn)
• Contagged - contagged - UTF-8 sorting-problems are solved
• Tagcloud: vge_tagcloud oder danp_tagcloud

Translation - Spell check

• Firefox dictionary for the language to check (available in many languages, contact Translation)
  • Firefox-Addons german
  • Firefox-Addons US-english

Projects

The problem with tx_party was that nobody helped in development, because it's a very big concept. Must be better than the table Projects. We need a database for projects, that helps new developers to find a good task they can do to contribute in a project. Should be RSS with categories so that it's easy to integrate into www.typo3.org - This should be a feature of the new documentation portal, so that's "project-management-documentation"

Tool-comparison Screenshots

Screenshot TYPO3/ tinyMCE as editor	Screenshot O3Spaces Workplace / Opening from server	Screenshot OpenOffice as editor + O3Spaces example "pear"
Screenshot GoogleDocs example "fdfx_3cols"	Screenshot wiki.typo3.org as editor example "typo3_tut"

Tool-comparison table

Thanks to Andreas Becker for the list of SaaS-tools and Susanne Moog for testing them!

• .sxw = Alternative documentformat of OpenOffice
• ODF = OpenDocumentFormat = international standard ISO/IEC 26300: .odt for texts, .ods for tables, .odp for presentations und .odg for drawings

Type of tool	Tool-Name	Diff-feature	Translations linked?	textlinks/ bookmarks in documents?	keywords/ tagging?	Pro / Con
SaaS	Google Docs	nicely done diffs with marking and showing what was changed where to what and by whom. Even in tables!!	no	no textmarks/ just hardlinks	no (only folder structuring)	+ fast and easy + export to word, OpenOffice and others + Maybe an advantage if we cooperate with Google + More Tools: Calendar for Events, Docs, Galleries, SVN, Forums, Mailinglists, Chat + no problem with two sizes A4/ Letter U.S. Canadian - No Template for new documents - little problem: colors get lost (like the light grey for all headers) - little problem: table of contents gets converted in simple text - little problem: footer is shown just on page 1 but is on every page after export - The document is on any server - people have to get a login who like to contribute (NO problem because very easy)
SaaS	O3Spaces Workplace o3spaces.com OpenOffice- Extension	?	?	yes, textlinks	?	++ mass-upload of documents as zip-file (in Studio-perspective) ++ very good usability and style of user-GUI and admin-GUI + o3spaces is the collaboration extension of OpenOffice + Template for new documents usable because all features of OpenOffice usable + much better overview than GoogleDocs (user-management, workspaces, folders) + real-time version control, check-in/check-out + as Debian or RedHatPackage, VMware, Windows + document security + no problem with two sizes A4/ Letter U.S. Canadian - the server needs Java with installed Tomcat info: install on Debian by shell: sudo dpkg -i /dc/PRG/OpenOffice/o3spaces-server_2.2_generic.deb
TYPO3 extension	pipeline pipeline_pdf (pipeline_pdf) (contact: krannich)	versioning-diff	yes: TYPO3 translations	yes, links to page/section-ids	yes: category- extension	+ it's TYPO3 + Virgil can sponsor the Webspace ++ Andreas is putting much effort in it --- no automatic page-breaks (the pipeline-extension has just fixed pages, is FPDF really limited?) ++ because TYPO3: every section can be limited to a single editor + because TYPO3: translations are easy + the manual is written as a TYPO3-page + the extension exports the content as PDF -- problem with two sizes A4/ Letter U.S. Canadian (Andreas: different amount of content needed for the two sizes) - The problem is that every editor has to have a BE-login for typo3.org
TYPO3 extension	dynamic pdf-renderer (already existing?)	versioning-diff	yes: TYPO3 translations	yes, links to page/section-ids	yes: category- extension	+ it's TYPO3 ++ because TYPO3: every section can be limited to a single editor + because TYPO3: translations are easy + the manual is written as a TYPO3-page + the extension exports the content as PDF / OpenOffice / OpenDocument + no problem with two sizes A4/ Letter U.S. Canadian - The problem is that every editor has to have a BE-login for typo3.org - is there a pdf-renderer extension what does automatic page-breaks? (the pipeline-extension has just fixed pages) Info from Ries: A html2pdf-renderer would not do the job - also xsl is needed
current	OpenOffice	diff function for texts, not for tables	no	yes, textmarks	yes: document properties	+ TYPO3 standard-Tool + no problem with two sizes A4/ Letter U.S. Canadian - No Teamwork possible (see also: o3spaces) - When the author has left TYPO3 it needs a long time to get the extensionkey for updates
current	Wiki.typo3.org	very good diff function, RecentChanges-list	yes: language-switch	yes, link to page/section-name	yes: tagging	+ no login needed + fast editing + Import and Export by Copy&Paste + no problem with two sizes A4/ Letter U.S. Canadian - Images are not easy to export and upload - Some people don't like the wiki-editor
DocBook	DocBook-Editor	--	no	yes, reference to paragraph	yes: keyword- tag	+ no problem with two sizes A4/ Letter U.S. Canadian + Vex is a WYSIWYG-editor for DocBook (sourceforge, based on Eclipse SWT, LGPL-licence, extensible, newest version 1.2.1 from 2005) - for the most people such an application is not easy enough. OpenOffice is not good enough for this.
SaaS	Zoho	diffs only underline where something was changed, they don't show what it was before the change	no	textmarks not tested	no	+ fast and easy to use + export to word,OpenOffice and others + no problem with two sizes A4/ Letter U.S. Canadian - The document is on any server - people have to get a login who like to contribute
SaaS	Think free	No diff function to find	no	textmarks not tested	yes	- quite slow - requires JRE - only saves documents in word format (.doc) - The document is on any server - people have to get a login who like to contribute
SaaS	Ultea	?	?	?	URL ?
TYPO3 extension	timtaw TimTaw (timtaw) (contact: sebastian)	versioning-diff	yes: TYPO3 translations	yes, link to page/ section-id	yes: category- extension	+ it's TYPO3 + translations are easy -- problem with two sizes A4/ Letter U.S. Canadian (Andreas: different amount of content needed for the two sizes) - every editor needse a BE-login for typo3.org - page-breaks are not automatic

Current Project Members

Daniel Brüßler	danielb - at - typo3.com	utf8 mysql, installation 4.1.6
Virgil Huston	virgil.huston - at - gmail.com	sponsors 2 TYPO3 subdomains
Susanne Moog	typo3 - at - susannemoog.de	likes to do tests

Wishlist

• Daniels Tasks
• Test: Translations utf8/symbolic languages
• Test: Very big documents with 200 pages
• Test: Import from OpenOffice by 1 klick
• Test: Check for structure and style before export to .sxw