Deprecated Features and the Wiki

[Santos]

Hi Andrew,

I know what you mean!

I tried to make a more efficient reference here: http://santos.nfshost.com/love092.html

It's not good, but it doesn't have any deprecated features (hopefully!) and everything is a Ctrl-F away.

As for the wiki, if possible it might be cool if each version could be separated, and maybe accessed like: https://love2d.org/wiki/0.8.0/love.graphics

If each version of the documentation is separate, there is no clutter from deprecated features, and if you're using a previous version you don't have the clutter of newer features you can't use.

[s-ol]

Hi Andrew,

I know what you mean!

I tried to make a more efficient reference here: http://santos.nfshost.com/love092.html

It's not good, but it doesn't have any deprecated features (hopefully!) and everything is a Ctrl-F away.

I like it actually! Of course the tips and examples from the wiki would be good to have there aswell.

As for the wiki, if possible it might be cool if each version could be separated, and maybe accessed like: https://love2d.org/wiki/0.8.0/love.graphics

If each version of the documentation is separate, there is no clutter from deprecated features, and if you're using a previous version you don't have the clutter of newer features you can't use.

I thought about this aswell, the only downside is that if you for example want to port something, all the version transitions and tips are gone. For example if you look at a 0.7.0 game right now and wonder about the Body:applyImpulse then you can go to the wiki page and it will tell you that function was removed, and also that it is now known as Body:applyLinearImpulse.

[pancreas]

Love the discussion. I hate to have a strong opinion here because I don't know enough to start throwing those out. I do like the "change the color of deprecated features slightly" option, only because it seems really simple to do and it's therefore more likely to happen.

Ideally, a filter or bottom-sorting the old stuff would appear more "maintained" to the casual observer, however.

-Andrew

[OttoRobba]

Something like this would be amazing:

https://atom.io/docs/api/v1.0.11/Atom

What could be done, for deprecated features, is adding a note to them explaining that they were deprecated at version x

[davisdude]

This is already done, they just aren't removed from the docs.
See 0.10.0

[OttoRobba]

This is already done, they just aren't removed from the docs.
See 0.10.0

No, that would be the change log.

The Atom documentation allows you to revise the entire API across all versions.
As an example, suppose you need to use Atom's CommandRegistry. You can see how it was modified in every version:
Version 0.191.0 vs Version1.0.11

This allows you to easily adapt features to new versions as you can see what changed within a large span of time without having to go through change logs.
You only see information for the version that you want to see - completely unlike the current implementation.

[Karai17]

Perhaps a simple solution would be to just move all of the deprecated/removed functions into a different table?

Code: Select all

LOVE 0.9.2
Canvas	Off-screen render target.	Added since 0.8.0	
Drawable	Superclass for all things that can be drawn on screen.		
Font	Defines the shape of characters than can be drawn onto the screen.		
Image	Drawable image type.		
Mesh	A 2D polygon mesh used for drawing arbitrary textured shapes.	Added since 0.9.0	
ParticleSystem	Used to create cool effects, like fire.		
Quad	A quadrilateral with texture coordinate information.		
Shader	Shader effect.	Added since 0.9.0	
SpriteBatch	Store image positions in a buffer, and draw it in one call.		
Texture	Superclass for drawable objects which represent a texture.	Added since 0.9.1	

LOVE 0.8.0
PixelEffect	Pixel shader effect.	Added since 0.8.0	Removed in 0.9.0

LOVE 0.7.0
Framebuffer	Off-screen render target.	Added since 0.7.0	Removed in 0.8.0

It's not perfect, but it would at least move older versioned content out of the way.

[slime]

How can that be accomplished with SMW?

[Karai17]

I was thinking just manually reorganizing the list pages so data is in several tables instead of one. Again, not the best solution, but maybe a step forward.

Have we considered ditching MediaWiki for something more documentation-oriented? We could revamp the wiki to be a community portal for love projects of course, but what about adopting something more suited for versioned documentation? Or just hosting several versions of the documentation that link forward (deleted functions from 0.7.0 could point towards 0.10.0's equivalent)?

[Karai17]

MkDocs looks to a pretty nifty documentation tool that renders Markdown into HTML using a default or custom theme. Converting from Mediawiki to Markdown shouldn't be too difficult. I used MkDocs for STI but recently switched to LDoc as LDoc is better suited for Lua projects.

Edit: Here is a very basic example I managed to create on my own in about an hour of fiddling with tools in a Linux VM. It's very not perfect but I was able to pull the 1100~ MediaWiki pages out of the wiki (I excluded all non-English and non-API pages) and convert them to Markdown using the tool I have linked above. I then created a default MkDocs project (with the readthedocs theme), dropped the Markdown in, and ran build. Out popped a 200~mb static website with the entire LOVE API.

With more options set and more time spent, we could probably whip up a very lovely theme and such.