Wiki Structure
lua-users home
wiki

Descriptions or discussions of the structure/organization of this wiki as it currently is. This is more descriptive than prescriptive.

The title of this page, "LuaAddons", I think is not the most descriptive. [According to Wikipedia] an "add-on" is more like a plugin, which for a language like Lua would be a module, which is listed on a separate page (LibrariesAndBindings). The emphasis of this particular page seems more to be tools that can be used for Lua development. You might specifically call many of these [CASE tools], mainly with the exception of the "Lua distributions" and "documentation" sections. Documentation is not obviously an add-on, and neither may be distributions. Note that LuaPowerPatches is partly related to distributions (i.e. patched/modified/custom versions of Lua itself), so some grouping of those pages might be done. --DavidManura

[LuaAddons] is for indexing "things for Lua users", including libraries, documentation, development tools, and distributions. "Lua addons" is perhaps not the best term, but the intended meaning is clarified in the first sentence of this page, and it's easier to say than "things for Lua users". --JohnBelmonte

Think of these three fuzzily-bounded parts: the contents of this wiki (LuaDirectory), external links regarding Lua proper (LuaLinks), and external links regarding everything else for Lua users (LuaAddons). I think it's spelled out clearly enough in the 3rd paragraph introducing this page. --JohnBelmonte

I've long felt the distinction between internal and external links is artificial for organizational purposes. Some things even exist both internally and externally (e.g. MetaLua v.s. [Metalua]). I recently moved the language comparison section from LuaLinks into LuaComparison for example. --DavidManura

On the HomePage, how do Featured Pages differ from Starting Points? For example, why is LuaDirectory not a Featured Page? --DavidManura

The starting points provide the major index pages of the wiki and the place to give feedback. These are by definition general and would never be featured pages. --JohnBelmonte

I tend to feel that the contents of LuaDirectory would be more useful on the home page, in some way, rather than as a subordinate link. The current structure feels somewhat inverted and disorienting. --DavidManura

Page names that would otherwise be a single word tend to be preceeded by "Lua" if appropriate, and only the first letter of an acronym is capitalized (e.g. LuaFaq not Faq or LuaFAQ). There are exceptions, e.g. LuaPowerPatches and IoLanguage.

users.lua.org may make more sense than lua-users.org, though this has been discussed here: http://lua-users.org/lists/lua-l/2001-07/msg00208.html .

LibrariesAndBindings and LuaForge have some overlap in purpose. LuaForge is larger (contains 215 projects), though not all of the projects registered there are modules. However, not all Lua projects are registered on LuaForge. Some projects are hybrids: registered on LuaForge but with files stored elsewhere. A few modules are just maintained informally on the wiki in the SampleCode section. Some modules are registered in the LuaRocks database. There is no central place comparable to CPAN for registering modules.

Suggested Lua Wiki Guidelines

The following are recommendations or what I think are good practices for this wiki. --DavidManura

(1) All code or pages should be marked with the Lua version it is intended to run on.

One example: 

-- Compatible with Lua 5.1 (not 5.0).
function test(t)
  print(t, # t)
end

A problem in the past was that people added Lua 4 examples to the wiki. Then Lua 5.0 followed by 5.1 came along, which often fails to recognize Lua 4 (and even sometimes Lua 5.0). However, the Lua 4 code remained on the wiki, and there was no hint of this to the reader. Asko agrees [1]. Marking the version as such will do much to solve the problem. In fact, this is already enforced on LuaPowerPatches. Also, if you find old code but don't have time at the moment to fit it, I recommend marking it with a VersionNotice.

Ideally, we'd want old Lua code on the wiki converted to the latest version of Lua. Still, I think it is ok, maybe desirable, to keep the old version as a footnote for historical reference. Just mark it as such.

(2) Proper syntax highlighting of interactive Lua sessions would be useful, as this occurs a lot on the wiki. You can use regular "Lua" syntax highlighting, which usually works ok but not always: 

> = "test if [["
test if [[
> = "test]]"
test]]

One version of the Perl code used by the wiki is at LuaToHtml. I'd like to offer a patch, but see comments there.

(3) Syntax highlighting for C.

This would help in the many C code examples. Requested also by RiciLake on GuestBook.

(4) Style recommendations for authoring pages

Based on editing a lot of pages, these are what I think are good practices for authors and editors to follow. Use the Lua syntax highlighting feature. Indent code examples to the right (as done in the Lua examples above) to set them off from the surrounding text. Avoid tabs, but rather use two spaces (or three), as follows the Lua Manual and PiL book style, and as I think is most suitable for the wiki medium. Avoid extra spaces in expressions as in x = f( x, y ) or { a , b } but rather use x = f(x, y) or {a, b}--in general use the most conventional style consistent with other pages on the wiki. Actually, I just found this: SourceCodeFormatter.

Some sets of pages are sufficiently similar in nature that they fall into certain classes, in which case some consistency can be imposed. One such example is SampleCode.

(5) Structure of the wiki

Some past comments on the overall wiki structure are in WikiStructure, but I'm still forming an opinion about the overall structure, and for now a higher priority is a review most of the wiki content as noted below.

(6) Periodic review of content.

Content on the wiki should be periodically reviewed for quality assurance, consistency, and correctness of content. As Lua changes and the Lua community changes, published content can become less correct over time (as in the Lua 4 case above shows). I'm currently working on my own review of much of the wiki content.

Pages to delete

These pages can be deleted.

Pages to move

These pages can be moved.

Other

1) It could be cleaned/updated. Most of links would just go to the LuaAddonsArchive.
2) It could simply be abandoned/removed. All its useful content (namely BEOS and Linux ARM/SH3 links) would be integrated into LuaDistributions.
I vote for the second. --DmitryGaivoronsky

LuaDirectory and categorization

See the new LuaDirectory structure proposal at my userpage: DmitryGaivoronsky. N.B.:
Some comments and section headings can sound odd (excuse my bad english) and should be fixed.
Some comments are missing.
Some sections haven't been thought over thoroughly and require more arrangement; some pages could be miscategorized.
I've invented a policy (and found it handy) to italicize links to all pages which contain directories, i.e. lists of links or submitted forms. It can be criticized though.
It can be pretty hard to create and maintain a consistent wiki structure without a native support for categories in the wiki engine. --DmitryGaivoronsky

I consider the terms LuaProgramming and LuaCoding essentially synonymous (i.e. writing out source code). The links on the LuaProgramming page deal with ways structures and patterns can be used and represented in Lua source code. The links on the LuaCoding page seems to deal more with the processes surrounding use and development of Lua code, basically the software engineering[2] aspects, which may even be outside of the Lua language itself. Therefore I tentatively suggest the page names LuaProgramming and LuaEngineering?. --DavidManura

As with previous restructurings like this, I can't say I'm in favor. Things are getting too fragmented across pages, hierarchies are getting deeper, cross-referencing increasing. This hits the weak points of wiki's, especially this simple wiki implementation. Yes monolithic pages aren't perfect, but they have advantages: less "places" (to become lost), less desire to start adding navigation aids everywhere, keeps a wider picture in one view, less need to repeat directory guidelines or policies (or omit them and deal with consequences). There is something to be said for constraints (e.g. limiting hierarchies to 2 deep). ** I don't agree with the use of italics for index page references-- it's a bit of an overuse of formatting for little gain. Will I really decide to visit a link or not based on whether it's an index? --JohnBelmonte

I see reason in the proposed reorganization, though I do have some of the concerns of John. Although LuaLanguage, LuaProgramming, and LuaCoding (a.k.a. LuaEngineering?) form a natural progression (define the language, use the language, and organize the use of the language), LuaDomains could be very intertwined with other pages.

I also think, perhaps, as a rule that an index page that a user would not think of going to should not exist. A typical user I think comes to the wiki to ask questions like "How do I define an object in Lua?" (solutions: ObjectOrientedProgramming), "How do I serialize an object?" (solutions: TableSerialization), "How should I structure modules?" (solutions: ModuleDefinition), "How do I do parallel programming?" (solutions: MultiTasking), "How do I bind non-Lua code to Lua?" (solutions: BindingCodeToLua), "Where can I find a 'batteries included' build of Lua for my platform?" (solutions: LuaDistributions), etc. As seen, there can be one page that is fairly comprehensive and coherent on the topic. Now for LuaLanguage, the question is "I'm looking for a more detailed description of the Lua language beyond that in the Reference Manual. Also show me various other random things under 'Enhancement Proposals and Third-party Modifications'." For LuaProgramming, the question is "How can I structure code to achieve a certain goal or improve quality?" For LuaCoding, the question is "What tools and methods, outside of the Lua language itself, can I use to achieve a certain goal or improve quality (which is somehow different from LuaAddons)?" For LuaDomains, the question is "Give me a topically categorized list of stuff." Of the four pages I think LuaProgramming (once called "Lua Fu") is the most coherent, and I considered extracting such a page myself. In fact, it has some similarities in purpose to the Lua Programming Gems book. If one wanted though, I think the LuaLanguage, LuaProgramming, and LuaCoding pages could be combined into a single page though perhaps maintain the same grouping. This combined page would address how to effectively achieve goals. Perhaps that page is LuaDirectory though. --DavidManura

JohnBelmonte, but wiki technology is not for less places, it's for more places. For not to become lost (both for reader to search/navigate and for editor to structure/maintain), people have invented categories. (Frankly speaking, all of this is mainly an effort to emulate MediaWiki-like categories[3]... Have you used them?). For not to repeating, people have invented templates. (Have you used them?) And I feel that trying to adapt the wiki structure to the wiki engine is not really a good idea. Instead, we should consider adapting the wiki engine to the wiki structure.
The reason for italics. Wiki technology suggests that for navigation and observability purposes, every page should be listed at least in one category/directory/index. The italicization idea has been born from the need to mark what is considered as such categories.
Cross-referencing inside the hierarchy is not a weak point. In fact, it is an essential feature of consistent categorization. Categories' hierarchy cannot be represented as a tree; it is a directed graph with no loops[4].
Limiting hierarchies to N depth levels for one page is a reasonable approach. Not to forcedly shallowing it on one page, but to extract deep branches to separate pages. (I would suggest the maximum depth of 4, to cut 5-level branch into e.g. 3- and 2-level parts). The depth of cross-page hierarchy should not be limited.
DavidManura, 'Engineering' ~= 'Software Engineering'. For me, LuaEngineering? reminds something like CAD/CAE systems (...somewhere in LuaDomains). --DmitryGaivoronsky

Yes I've used wiki categories on a wiki over 10 years ago. You can even do it on a simple wiki like this by having several pages reference a category page and using the back-reference feature. But when I started the lua-users wiki in 2001 I made a conscious effort not to introduce such complications and avoid many similar pitfalls of wiki confusion I had encountered in my experience. I was quite familiar with feature-laden wiki engines at the time an in subsequent years. Even starting with this simple engine, I spent a bit of effort pulling features out to keep things simple. The task of organizing and categorizing things can be overdone, and the importance of content-- the real value-- lost. The reorg you've undertaken since around the start of the year has gone against the grain of my conscious intentions for the site, but I don't want to be a dictator. I value David's opinion as he's put a lot of care concerning content and organization into this wiki over the years, so I'd ask that you please consider his advice and feedback. ** I think you misunderstand what I mean by limiting hierarchy level. I'm referring to inter-page hierarchies, not heading hierarchies within a page. In other words I want less pages, not more. --JohnBelmonte

(Software) engineering/construction indeed may only be a weak improvement. The wiki does in a way support categories (e.g. ObjectOrientedProgramming). The feature that causes clicking on a page title to provide an alphabetically sorted list of pages that link to it (backlinks) is fairly low-level and probably not obvious to most users. Furthermore, "A links to B" is a more general relationship than "A is a sub/super-category of B". However, this feature is quite useful for wiki authors to check that a page is properly cross-linked and parented (and if not to manually fix it). --DavidManura

LuaDocumentation (part of LuaAddons) and LuaLanguage overlap a bit in purpose. Also, given John's description up top of "external links regarding Lua proper (LuaLinks), and external links regarding everything else for Lua users (LuaAddons)" and my characterization "LuaLanguage, LuaProgramming, and LuaCoding (a.k.a. LuaEngineering?) form a natural progression (define the language, use the language, and organize the use of the language)", one might at least partly make the analogy LuaLinks is to LuaLanguage/LuaDocumentation as LuaAddons is to LuaCoding. I think LuaAddons (including LuaDocumentation, LuaTools, LibrariesAndBindings, ...) tends to deal with concrete things (files/libraries/plugins/utilities), while LuaLanguage and LuaCoding tend to deal more with topics, problems, descriptions, and thought processes. LuaDomains may be a combination of both. --DavidManura

I think LuaPowerPatches belongs as a top-level link in LuaAddons rather than as much on the home page (though "patches" could still be listed in the description of the LuaAddons link). Patches are in the same league as distributions, implementations, editor plugins, libraries, and tools.--DavidManura

LuaPowerPatches is the most significant page on this wiki in terms of impact on the Lua community. I'm quite sorry to see it removed as a featured link on the home page. --JohnBelmonte

I too had some hesitation on that. LuaPowerPatches could be a featured item, though it is already contained in LuaAddons. Some of the other LuaAddons such as LibrariesAndBindings, LuaDistributions, and LuaImplementations are quite significant too. However, patches have a somewhat special significance in Lua compared to other languages, so I understand the desire to keep it prominent. I'm not entirely set on the current presentation of patches on the home page. I feel LearningLua and LuaComparison are significant enough to be featured too, though they are already prominent in LuaFaq. --DavidManura

I don't currently have a strong opinion of the LuaDirectory page breakup in DmitryGaivoronsky. However, if it was further reduced (e.g. moving the Community section into a new page LuaCommunity?), then LuaDirectory would likely be mergeable into HomePage, which follows my thought in the top section of WikiStructure.--DavidManura

I'd prefer the home page remain as I wrote it originally-- small and under 10 links. --JohnBelmonte

The proposed directory structure in DmitryGaivoronsky mixes very broad views (e.g. LuaLanguage, LuaAddons, LuaDomains, ...) with more specific links (e.g. GoogleSummerOfCodeIdeas). I suggest one or the other. Below is what it might look like using only broad links (which is approx. 10 links). --DavidManura

Logically, Introduction should belong to LuaLanguage. I've leaved Introduction and Community at the top level mostly for convenience and to fill the space. They can be too small to deserve separate pages; but if you feel it more consistent this way, I don't mind. However, I believe we should avoid any links inside the comments--they will scarcely be used directly but create more mess in the list. --DmitryGaivoronsky

That makes sense. Below is a rework of it. The top-level list are the main category sections. The second level lists are important featured pages (if any) in those sections. I'm not confident about the need to separate LuaProgramming and LuaDomains (see previous comments above concerning LuaDomains). --DavidManura

I suggest not to pickup any "important" or "featured" pages. It is very subjective matter. It should be realized that if lua-users be more popular, this would lead to wiki wars (filtering -> reversions -> censorship). After all, LuaDirectory "is a top level directory of all Lua content at this wiki", and the Featured pages section is at the HomePage.
Another choice would be to leave and gather at second level only italicised links (i.e. directories). It is a formal criterion which is pretty simple to maintain and pursue. (But can be too formal for comfortable use -- that's why in my original proposal I've permitted some exceptions.)
It can be unclear, but... All of this is just attempts to invent something that is actually invented already. I am still hinting at Mediawiki-like categories (as russians say, "why we should try to invent a bicycle?"). --DmitryGaivoronsky 

The task of organizing and categorizing things can be overdone, and the importance of content-- the real value-- lost.
--JohnBelmonte
It is pretty hard to speak about any importance of content when most of it is buried underground. This wiki has really many pages, but many of them have pretty no chances to be viewed by average user. (I've found it more handy to leech all lua-users content at once with wget than read it following hyperlinks.) It is very hard to find anything in a heap of unorganized things (russian saying: "to search a needle in a rick of hay"). So, I believe the proper question is: Is the engine scalable for so many pages? (Can you prove that?) --DmitryGaivoronsky

DavidManura, we can merge Algorithms section from LuaProgramming with LuaDomains. This will provide us with LuaAlgorithms?. But... Not all entries in LuaDomains are really Lua algorithms. (So, in formal terms, LuaDomains and LuaAlgorithms? are parallel categories, while LuaAlgorithms? is subcategory of LuaProgramming.) --DmitryGaivoronsky

See Also

RecentChanges · preferences
edit · history
Last edited November 27, 2009 4:49 pm GMT (diff)