Related
I'm part of team working on SDK that is exposed with several programming languages - currently ObjC, C#, ActionScript, Java (Android) and later we'll have even more languages.
We want to have documentation which is made up of two parts:
Human readable documentation
API Reference
There are links between the two parts: from human readable docs we have links to specific classes or methods and from the API reference we may link to a document that explain the context in which the class or method is used.
We are currently use a combination of sphinx for human readable documentation and language specific tools for API such as doxygen or asdoc
I saw in LeapMotion they were able to generate a complete documentation for multiple programming-language (not human language) with cross links between programming-languages.
The Question
Does someone know how to accomplish such documentation system in a way we'll not have to duplicate each change in human readable docs to every language and have cross links between the languages?
I put together the Leap Motion documentation. I use Sphinx to create the package of docs and Breathe, a Sphinx plug-in, to basically import XML files generated by Doxygen into the Sphinx project for the doxygenated API references (C++, C#, Java, and Objective-C). For links from the so-called "human-readable" pages to the API references, I generate RST substitutions from the .tag files which Doxygen will generate for you. Links from the API reference to the "human-readable" pages are normal, relative hyperlinks (which I should add more of).
I use the conditional content features of Sphinx to generate a separate set of docs (both "human-readable" and API) for each programming language. Thus these articles can be customized for each programming language where needed and have the correct code examples for the current language. Because each doc set has the same structure, it isn't hard to switch from one language to another.
I did add some custom JavaScript to the page templates to help switch between languages.
tl;dr: Sphinx, Breathe, Doxygen and a small amount of custom JavaScript.
If you would like to discuss this further, you can post a question to our (Leap Motion) developer forum. I'll see it (Stackoverflow isn't the proper place for an ongoing discussion).
Hi Ido Ran,
Tools which you've specified are best in industry for documentation purpose,I am afraid there is no such tool yet which could provide both human and as well as API reference.Out of all my personal best is doxygen which is slighly of multi-use (human and API)..Hope this helps.
I come from the ruby and python worlds where we have many libraries that can syntax highlight arbitrary code from many languages. I am looking for something similar in the objc ecosystem, but i can't seem to find such, is there one available?
The equivalent libraries in Ruby would be CodeRay and Pygments for Python,
thanks in advance!
Banister,
I myself have searched for a long time for a nice and robust Cocoa Syntax Highlighter, and since I'm currently building a code-oriented text editor myself, that would be a major part of the project.
So, I found out that there are plenty of Objective-C/Cocoa -friendly Syntax Highlighting libraries/components. For a starter (for something relatively basic, that is), I would suggest you have a look at :
OkudaKit (using CSS for styling)
UKSyntaxColoredTextDocument by Uli Kusterer (pretty nice try)
However, if you really need something POWERFUL, well-tested and still Cocoa-friendly, I would definitely suggest you to try the Scintilla component (for Cocoa). The code is great, and the community (at Scintilla-Interest Group) will gladly help you iron out any issues you may encounter.
In a few words :
I'm currently using on an about-to-be-release big project and it's working beautifully for me.
Scintilla
Scintilla is a free library that provides text-editing functions, with
an emphasis on advanced features for source code editing. SciTE
(cross-platform), Geany, Notepad++ (Windows), and Notepad2 (Windows)
are examples of standalone editors based on Scintilla.
Scintilla Editing Component in use (SciTe)
Features
Scintilla supports many features to make code editing easier in
addition to syntax highlighting. The highlighting method allows the
use of different fonts, colors, styles and background colors, and is
not limited to fixed-width fonts. The control supports error
indicators, line numbering in the margin, as well as line markers such
as code breakpoints. Other features such as code folding and
autocompletion can be added.
Download Scintilla (the Cocoa support has been integrated in the main project) : http://www.scintilla.org/SciTEDownload.html
Example project (integrating Scintilla with Cocoa) :
http://bazaar.launchpad.net/~mike-lischke/scintilla-cocoa/trunk/files/head:/cocoa/ScintillaTest/
For complete documentation, have a look at : Scintilla
Documentation
Fragaria may be useful for future reference.
I'm looking for an editor/IDE that can provide features that are nice to have while coding (example: being able to click-through to function definitions) for languages that it is not specifically built for. By these, I have in mind languages designed for a very specific purpose and often only used by a small community. In other words, ones that would not have native support in most software.
I realize this would require a fair bit of fairy dust but I don't think it's out of the scope of what's possible. Basically, the editor would have to be smart enough to recognize the commonly used syntax and semantics that many declarative languages have in common. It's quite possible this would require some amount of configuration.
Does something like this exist? If not, what challenges do you think there would be in creating it?
If you need only the feature to jump of to the definition of a specific function or class, then VIM (and many other editors, like Emacs, Epsilon and JOE) can read the jump location from the ctags file. You just have to write a ctags file generator for your custom language.
For programmable editors (like VIM, Emacs, Epsilon, Eclipse and gedit), you can write your own plugin for your custom language, but it may quickly become time-consuming and a maintenance nightmare, because new versions of editors tend to change the plugin interface.
Please note that adding support for syntax highlighting is usually much easier than adding ctags-like support for symbol lookups. More advanced features, like refactoring and context-sensitive symbol completion (like Ctrl-Space and Tab in modern IDEs) are even harder to implement.
GNU Emacs has a pretty good infrastructure for this sort of thing. Until recently Haskell was a relatively unknown language used primarily by researchers. Nevertheless, in a few thousand lines of Emacs Lisp, we have
Syntax highlighting with colors
Automatic indentation
Package support
Automatic highlighting of type and other information when placing the cursor over library functions
Meta-dot on an identifier to jump to its definition (through the standard emacs tags mechanism)
The nice thing about Emacs is that (a) there are many models to follow, and (b) you can build up the environment gradually, starting with those aspects that are most important to you.
I'm suprised no one has mentioned Notepad++ yet:
http://notepad-plus-plus.org/
It offers syntax support for a great many languages and offers the user to add new languages, and an active community that adds many languages that are not included out-of-the-box.
Most good IDE's are language agnostic and supports several if not many programming languages. If you are talking about DSL's, eclipse has a solution that seems pretty awsome - Xtext
EditPadPro comes with a set of tools that allow you to build your own syntax highlighting, code folding and file navigation schemes, based on a very powerful regex syntax. So if your language is not among the many that have already been provided out-of-the-box or can be downloaded off the website, you can roll your own quite easily (and share it with the community).
Visual Studio is designed to allow for this, but it requires the language to add explicit support. For example, Delphi Prism will install into Visual Studio, and provide full language support.
This is far above and beyond "configuration", however, and requires quite a bit of custom development to support.
SciTE and Scintilla offer a generic editor/platform for different languages. The library contains several parsers that work with many programming languages and you can reuse one of these for your own language to add formatting and syntax highlighting.
They don't offer advanced features like click-throughs, but you could build it on top of the library.
Visual Studio and Eclipse also support language plug-ins.
Zeus is a language neutral IDE for the Windows platform and it provides this go to definition/declaration functionality for any language supported by ctags.
To make it work you just create a Zeus project/workspace and then add the files to this workspace.
If I were looking to create my own language are there any tools that would help me along? I have heard of yacc but I'm wondering how I would implement features that I want in the language.
Closely related questions (all taken by searching on [compiler] on stackoverflow):
Learning Resources on Parsers, Interpreters, and Compilers
Learning to write a compiler
Constructing a simple interpreter
...
And similar topics (from the same search):
Bootstrapping a language
How much of the compiler should we know?
Writing a compiler in its own language
...
Edit: I know the stackoverflow related question search isn't what we'd like it to be, but
did we really need the nth iteration of this topic? Meh!
The first tool I would recommend is the Dragon Book. That is the reference for building compilers. Designing a language is no easy task, implementing it is even more difficult. The dragon book helps there. The book even reference to the standard unix tools lex and yacc. The gnu equivalent tools are called flex and bison. They both generate lexer and parser. There exist also more modern tools for generating lexer and parser, e.g. for java there are ANTLR (I also remember javacc and CUP, but I used myself only ANTLR). The fact that ANTLR combines parser and lexer and that eclipse plugin is availabe make it very comfortable to use. But to compare them, the type of parser you need, and know for what you need them, you should read the Dragon book. There are also other things you have to consider, like runtime environment, programming paradigm, ....
If you have already certain design ideas and need help for a certain step or detail the anwsers could be more helpful.
ANTLR is a very nice parser generator written in Java. There's a terrific book available, too.
I like Flex (Fast Lex) [Lexical scanner]
and Bison (A Hairy Yacc) [Yet another compiler compiler]
Both are free and available on all *NIX installations. For Windows just install cygwin.
But I old school.
By using these tools you can also find the lex rules and yacc gramers for a lot of popular languages on the internet. Thus providing you with a quick way to get up and running and then you can customize the grammers as you go.
Example: Arithmetic expression handling [order of precedence etc is a done to death problem] you can quickly get the grammer for this from the web.
An alternative to think about is to write a front-end extension to GCC.
Non Trivial but if you want a compiled language it saves a lot of work in the code generation section (you will still need to know love and understand flex/bison).
I never finished the complete language, I had used rply and llvmlite implements a simple foxbase language, in https://github.com/acekingke/foxbase_compiler
so if you want use python, rply or llvmlite is helpful.
if you want use golang, goyacc maybe useful. But you should write a lexical analyzer by hard coding by hand. Or you can use https://github.com/acekingke/lexergo to simplify it.
As already discussed in "Lua as a general-purpose scripting language?" Lua currently probably isn't the best scripting language for the desktop environment.
But what do you think about the future? Will Lua get so popular that there will soon be enough libraries to be able to use it like Python, Ruby or something similar?
Or will it simply stay in it's WoW niche and that's it?
I think it has a great future, a lot of projects are starting to adopt it for it's simplicity and usefulness.
Example: Awesome WM (Window Manager)
The project recently released version 3, incorporating a new configuration system completely written in Lua. Allowing you to literally write your configuration file as a program, loops, booleans, data structures.
Personally I love the syntax and the flexibility of such a system, I think it has great potential.
I wouldn't be surprised if it became more popular in the future.
Brian G
I suppose the answer starts with 'It depends how you want to use it...'.
If you're writing the common business app (fetch the data from the database, display the data in a web page or window, save the data to the database), Lua already has what you need.
The Kepler Project contains goodies for web development. Check out their modules to see some of the available libraries - there's network, MVC, DBMS access, XML, zip, WSAPI, docs...
As an example web app, check out Sputnik.
For desktop UI, there's wxLua - Lua hooks for wxWidgets.
ORM is conspicuously missing but that didn't stop people from developing in other languages before ORM was available.
If you're looking for specialized libraries - scientific, multimedia , security - don't count Lua out before you check LuaForge.
When it comes down to it, there's nothing in Lua's design that prevents general purpose use. It just happens to be small, fast, and easy to embed... so people do.
Uh? I would say instead WoW is a niche in the Lua ecosystem... The world of Lua doesn't revolve around WoW, there are lot of applications, some big like Adobe Lightroom (to take a non game), using Lua.
Lua is initially a scripting language, in the initial sense, ie. made to be embedded in an application to script it. But it is also designed as an extensible language, so we will see progressively more and more bindings of various libraries for various purposes.
But you will never get an official big distribution with batteries included, like Python or Perl, because it is just not the philosophy of the authors.
Which doesn't prevent other people to make distributions including lot of features out of the box (for Windows, particularly, where it is difficult to build the softwares).
Lot of people already use it for general system-level scripting, desktop applications, and such anyway.
There are more and more libraries for Lua.
If you are a Windows user, have look at Lua for Windows. It comes with "batteries included" (wxLua, LuaCURL, LuaUnit, getopt, LuaXML, LPeg...).
Very usefull!
It's 2017, 9 years after this question was first asked, and lua is now being heavily used in the field of machine learning due to the Torch library.
I really like it as an embedded language. It's small, very easy to use and embed and mostly does what I need right out of the box. It's also similar enough to most languages that it has never really been an issue for me. I also like how easy it is to redefine and add base functions and keywords to the language to suit whatever needs my application has.
I have used it in the WoW area but I've also found it useful as a generic scripting language for a number of different applications I've worked on, including as a type of database trigger. I like Ruby and Python and other more full-featured scripting languages but they're not nearly as convenient for embedding in small applications to give users more options for customizing their environments.
being comfortable as a shell language has nothing to do with being a great general purpose language.
i, for one, don't use it embedded in other applications; i write my applications in Lua, and anything 'extra' is a special-purpose library, either in Lua or in C.
Also, being 'popular' isn't so important. in the Lua-users list periodically someone appears that says "Lua won't be popular unless it does X!", and the usual answer is either: "great!, write it!", or "already discussed and rejected".
I think the great feature of Lua is, that it is very easily extensible. It is very easy to add the Lua interpreter to a program of your own (e.g. one written in C, C++ or Obj-C) and with just a few lines of code, you can give Lua access to any system resource you can think of. E.g. Lua offers no function to do xxx. Write one and make it available to Lua. But it's also possible the other way round. Write your own Lua extension in a language of your choice (one that is compilable), compile it into a native library, load the library within Lua and you can use the function.
That said, Lua might not be the best choice as a standalone crossplatform language. But Lua is a great language to add scripting support to your application in a crossplatform manner (if your app is crossplatform, the better!). I think Lua will have a future and I think you can expect that this language will constantly gain popularity in the long run.
Warhammer Online, and World of Warcraft use it for their addon language I believe.
I think it's hot! I'm just no good at it!
Well, greetings from 2022.
It is already a general purpose language. Today you can even serve pages using OpenResty, extend games, read databases or create scripts as shellscript replacements.
There are a plenty of libraries "modules" for Lua, many ways to achieve what you are wanting and Lua 5.4 is even faster.
The "extendable and extensive" nature of Lua, accostumed people to think it should only be used as plugin or extension. In Linux, by example, you can shebang a file with lua-any, make it executable and run like any system script. Or you can make a folder app like Python or virtualenv using Lupe. Lua 5.3 also gained impressive performance improvements.
Also there are many good tools like IUP to create native windows in Lua for Mac, BSD, Linux and Windows and side environments like Terra that lets you use Lua with its counterpart Terra and write compiled programs. Lua now, is more than a extension language, it has its own universe.