Difference between revisions of "Ideas"

From GNUstepWiki
Jump to navigation Jump to search
m
 
(8 intermediate revisions by 5 users not shown)
Line 1: Line 1:
 +
Everybody loves to tinker. Ideas on future development should go here.
 +
 +
See also the different [[Wish list|wish lists]].
 +
__TOC__
 
== Autogsdoc and wiki syntax ==
 
== Autogsdoc and wiki syntax ==
  
Line 5: Line 9:
 
<nowiki>Italics should be marked by ''italics'', bold by '''bold''' (mediawiki) or by __bold__ (phpwiki)</nowiki>
 
<nowiki>Italics should be marked by ''italics'', bold by '''bold''' (mediawiki) or by __bold__ (phpwiki)</nowiki>
  
−
<nowiki> The references should be: [[Class:class_name]], [[Method:Class:methodName:]], [[ivar:ivarname]]</nowiki>
+
<nowiki> The references should be: [[Class:class_name]], [[Method:Class:methodName:]], [[framework:framework name in local documentation namespace]]</nowiki>
 +
 
 +
<nowiki>The requirement of specificaly marking instance variables should be reconsidered. Italics should be used instead. Firstly, it is already common. Secondly, there is no need to preserve an information in the documentation that specified word is a function argument or an instance variable. The information is obvious to the reader from context and already used different font.</nowiki>
 +
 
  
 
XML is a bit complicated for such simple task as documentation.
 
XML is a bit complicated for such simple task as documentation.
 +
 +
I'd suggest something like ruby's rdoc [http://www.ruby-doc.org/stdlib/libdoc/rdoc/rdoc/index.html] --[[User:Frederik|Frederik]] 19:34, 27 Feb 2005 (CET)
 +
 +
=== Current actual documentation setup ===
 +
 +
The above seems to be based on a misunderstanding of how GNUstep documentation is generated and what the tools do.
 +
 +
The XML documentation language (gsdoc) is an intermediate format generated by autogsdoc, and from which standard tools like xslt can be used to generate other documentation formats.  The actual markup used by autogsdoc is extremely simple.
 +
 +
eg.
 +
 +
To cross reference the NSArray class you write [NSArray] (ie class name within square brackets).
 +
 +
To reference a class method you might write +arrayWithobjects: (ie the method name prefixed with a +).
 +
 +
To reference an instance method you might write -descriptionWithLocale: (ie the method name prefixed with -).
 +
 +
To reference a method in a particular class you might write [NSDictionary-description] (class name and method both within square brackets).
 +
 +
To reference a function you write its name followed by brackets (eg. NSLog())
 +
 +
Users can also embed gsdoc markup (though it's rarely needed), typically for html-style list or text formatting.
 +
 +
=== Doxygen ===
 +
 +
It does most of the cross-referencing automatically and is way more powerful.
 +
 +
The SideStep (and Etoile?) people and libFoundation already use
 +
Doxygen. See http://libfoundation.opendarwin.org/docs/ for
 +
libFoundation. To see how the GNUstep source tree documentation looks
 +
like, first install Doxygen, then do:
 +
 +
cd /tmp
 +
svn co svn://svn.gna.org/svn/sidestep/trunk sidestep
 +
cd sidestep
 +
<edit Doxyfile.in -> replace "@DOTDIR@" by the path containing the dot
 +
  tool. If you don't have graphviz installed, set HAVE_DOT to NO
 +
  instead. You can also use 'doxywizard <file>' to configure stuff.>
 +
doxygen Doxyfile.in
 +
 +
and wait for it to finish (it generates no output except warnings). [[User:Madleser|Madleser]] 16:17, 2 October 2006 (CEST)
 +
 +
== New Approach to a Code Editor ==
 +
 +
Developers should focus on development and not mess with files. Synchronizing header files with source files is no fun, neither is having to jump around for documentation of different methods and such. See http://ide.roard.com/wakka.php?wiki=Goals for some brainstorming on this topic.
 +
 +
== Help Center and Librarian In One Application ==
 +
 +
Use Yen-Ju Chen's [[MyLibrary.app]] as the help center and the answer to Nextstep's Librarian. Applications install their help files where MyLibrary can find and index them and taadaa, you have a note keeping, help storing and things-of-your-choice indexing application all in one! The only thing that would be even better is an enhanced Spotlight clone to do all of the above on all platforms.
 +
 +
== Better integration into Gnome/KDE/Windows desktops: AppWrapper.app ==
 +
 +
A script of some sort that, once run, collects information about the user's preferences. Is Gnome, KDE or Windows running?  Which apps can handle which MIME types?  Which icons do they have? This information is saved in separate application bundles and make_services is run.  Documents for which there is no GNUstep app installed will fallback on Gnome/KDE/Windows alternatives and for other files, the user has the choice. Generated App bundles should be flagged to make updating of apps easier, e.g. when the user installs other apps.
 +
 +
==XIB codec using NSKeyedArchiver==
 +
Here is a [[XIB]] file I have begun decodeing, it really is quite a simple format, what is more important is insuring that the NSObjects encode and decode themselves using the correct attribute names.

Latest revision as of 21:16, 16 July 2012

Everybody loves to tinker. Ideas on future development should go here.

See also the different wish lists.

Autogsdoc and wiki syntax

The class documentation should have simpler syntax than XML. For example a wiki-like syntax, where references would be enclosed in [[ and ]] for the ObjectiveC message sends, one should prefix the first [ by a backslash. Like: \[[alloc] init].

Italics should be marked by ''italics'', bold by '''bold''' (mediawiki) or by __bold__ (phpwiki)

The references should be: [[Class:class_name]], [[Method:Class:methodName:]], [[framework:framework name in local documentation namespace]]

The requirement of specificaly marking instance variables should be reconsidered. Italics should be used instead. Firstly, it is already common. Secondly, there is no need to preserve an information in the documentation that specified word is a function argument or an instance variable. The information is obvious to the reader from context and already used different font.


XML is a bit complicated for such simple task as documentation.

I'd suggest something like ruby's rdoc [1] --Frederik 19:34, 27 Feb 2005 (CET)

Current actual documentation setup

The above seems to be based on a misunderstanding of how GNUstep documentation is generated and what the tools do.

The XML documentation language (gsdoc) is an intermediate format generated by autogsdoc, and from which standard tools like xslt can be used to generate other documentation formats. The actual markup used by autogsdoc is extremely simple.

eg.

To cross reference the NSArray class you write [NSArray] (ie class name within square brackets).

To reference a class method you might write +arrayWithobjects: (ie the method name prefixed with a +).

To reference an instance method you might write -descriptionWithLocale: (ie the method name prefixed with -).

To reference a method in a particular class you might write [NSDictionary-description] (class name and method both within square brackets).

To reference a function you write its name followed by brackets (eg. NSLog())

Users can also embed gsdoc markup (though it's rarely needed), typically for html-style list or text formatting.

Doxygen

It does most of the cross-referencing automatically and is way more powerful.

The SideStep (and Etoile?) people and libFoundation already use Doxygen. See http://libfoundation.opendarwin.org/docs/ for libFoundation. To see how the GNUstep source tree documentation looks like, first install Doxygen, then do: 

cd /tmp
svn co svn://svn.gna.org/svn/sidestep/trunk sidestep
cd sidestep
<edit Doxyfile.in -> replace "@DOTDIR@" by the path containing the dot
 tool. If you don't have graphviz installed, set HAVE_DOT to NO
 instead. You can also use 'doxywizard <file>' to configure stuff.>
doxygen Doxyfile.in

and wait for it to finish (it generates no output except warnings). Madleser 16:17, 2 October 2006 (CEST)

New Approach to a Code Editor

Developers should focus on development and not mess with files. Synchronizing header files with source files is no fun, neither is having to jump around for documentation of different methods and such. See http://ide.roard.com/wakka.php?wiki=Goals for some brainstorming on this topic.

Help Center and Librarian In One Application

Use Yen-Ju Chen's MyLibrary.app as the help center and the answer to Nextstep's Librarian. Applications install their help files where MyLibrary can find and index them and taadaa, you have a note keeping, help storing and things-of-your-choice indexing application all in one! The only thing that would be even better is an enhanced Spotlight clone to do all of the above on all platforms.

Better integration into Gnome/KDE/Windows desktops: AppWrapper.app

A script of some sort that, once run, collects information about the user's preferences. Is Gnome, KDE or Windows running? Which apps can handle which MIME types? Which icons do they have? This information is saved in separate application bundles and make_services is run. Documents for which there is no GNUstep app installed will fallback on Gnome/KDE/Windows alternatives and for other files, the user has the choice. Generated App bundles should be flagged to make updating of apps easier, e.g. when the user installs other apps.

XIB codec using NSKeyedArchiver

Here is a XIB file I have begun decodeing, it really is quite a simple format, what is more important is insuring that the NSObjects encode and decode themselves using the correct attribute names.

Retrieved from "https://mediawiki.gnustep.org/index.php?title=Ideas&oldid=6391"