ℹ️
Welcome to the archive of the old FlatPress support forum. Browse more than a decade of FlatPress wisdom! Login is disabled.

The current FlatPress support forum is available here: forum.flatpress.org
Flatpress Code Documentation
  • pierovdfnpierovdfn
    Hi everyone. Flatpress is very interesting and there are a lot of PHP Programmers that would like to write new plugins but they don't know how to interface with the system code. So we could do together a knowledge. Is there anybody interested in this project? I think also translator are important for people that don't speak English as first language, like me. We could use the wiki but we have to decide how to structure all the documentation...
  • oonetoonet
    This sounds great! I would be happy to help :-)
  • pierovdfnpierovdfn
    oonet said:
    The wiki works. Though my preference would be to use Flatpress instead. Core documentation could be created as entries and/or static pages by an administrator, with visitor contributions made through comments . . . or add an ACL and work on the documentation more collaboratively.

    Sorry but I think a wiki is the best way to do this, at least for two reason: the first - more pratical - is that there is already dokuwiki installed on the server; the second is that it has a lot of useful tools like revisioning (if someone vandalize it), multi-language support (dokuwiki in paricular has a plugin)... We have to be open to users... Flatpress isn't ready yet to handle this type of function.
  • oonetoonet
    pierovdfn said: Sorry but I think a wiki is the best way to do this

    Whatever you think best :-) My preference for Flatpress is because it is simple and elegant . . . and because that is what is being documented.
    pierovdfn said: the first - more pratical - is that there is already dokuwiki installed on the server

    But not Flatpress?
    pierovdfn said: lot of useful tools like revisioning (if someone vandalize it)

    • Are you saying that Flatpress overly vulnerable to vandalism?
    pierovdfn said: multi-language support (dokuwiki in paricular has a plugin)

    Worst case, Flatpress could run a separate instance for each language. How many languages are we talking about? Maybe something could be written to swap menus.
    pierovdfn said: We have to be open to users...

    Yes :-)
    pierovdfn said: Flatpress isn't ready yet to handle this type of function.

    But wouldn't it be nice if it could? :-)
  • pierovdfnpierovdfn
    The Flatpress installation of the server is made for news about Flatpress or articles made from the project administrator (NoWhereMan, others?). Instead the dokuwiki installation is for users.
    oonet said: Are you saying that Flatpress overly vulnerable to vandalism?

    If everybody can edit what he wants without a revision mechanism, yes. However we talked in the other topic about multi-users...
    oonet said: But wouldn't it be nice if it could? :-)

    Yes, so we are documenting Flatpress to know where it could be modified. Now it isn't ready. To modify it users need time and the need to know how it works. It more users know how it works, they can work on it to extend so we need less time. The time we gain can be used for real life (of course ;) ) or to improve it and make Flatpress even better. So, now it's better using Dokuwiki that is ready.
  • oonetoonet
    pierovdfn said: Instead the dokuwiki installation is for users.

    Right. Without modification, Flatpress can accept visitor contributions directly as comments or through a moderator who does the actual posting. With minor modification, visitors could be given the ability to contribute entries. (With more or less of an ACL, this could be expanded.) Another possible enhancement would be to let contributors mark up existing articles to link to their contributions, as in a wiki. How many contributors do you expect right now? Could they all be trusted with administrator access to a Flatpress powered documentation site?
    pierovdfn said: If everybody can edit what he wants without a revision mechanism, yes.

    That's a good question. Is there reason for everyone to have access to edit whatever they want? If so, then a fair amount of effort might be needed for revisions. Both Docuwiki and Flatpress offer a number of options. Without revision, maybe Flatpress would be acceptable. With slight revision, maybe Flatpress could be as good as Docuwiki. (That's not counting the benefits of Flatpress that might make it better.) I'm not arguing one way or the other. It's just that computer software sometimes suffers from overspecialization. If we like what Flatpress does, maybe we would like to use it instead of something else.
    pierovdfn said: Yes, so we are documenting Flatpress to know where it could be modified.
    Now it isn't ready. To modify it users need time and the need to know how it works.

    I agree that it doesn't make sense to load down the documentation project with too many side issues. What I'm not sure of is that extending the usefulness of Flatpress in a real world application (collaborative documentation) is really a side issue. It would not be difficult to use Flatpress unmodified for the first pass at documentation. Thinking about its limitations creatively could add another dimension to the documentation to make it more useful - and easier to write. Just writing straight documentation is like writing a telephone directory. Boring and time-consuming. This feature does this, that feature does that. The more you say about a feature, the more difficult it is to read. On the other hand, if you are using Flatpress for documentation instead of Docuwiki, you are thinking of ways it could be improved to make the project easier. As you write about a particular feature, it occurs to you how useful it might be for adding what you want. And if it's simple enough, you might even write the code to do it. If you like Flatpress, then you might also like to use it instead of something else. It's not critical. I just think it might be fun to do things this way. :-)
    pierovdfn said: It more users know how it works, they can work on it to extend so we need less time. The time we gain can be used for real life (of course ;) ) or to improve it and make Flatpress even better.

    This is very sensible :-)
  • pierovdfnpierovdfn
    For me all the users should be able to edit the pages. However the software we should use doesn't matter for me: I use what I find. But it's better if the documentation is in flatpress.org or in one of its subdomains. About docs... Where do we start from? index.php? defaults.php? Alphabetic order?
  • oonetoonet
    pierovdfn said: For me all the users should be able to edit the pages.

    I like this approach myself :-)
    pierovdfn said: But it's better if the documentation is in flatpress.org or in one of its subdomains.

    Ah, yes. I'm so used to hosting the services under discussion that I forgot about this one! Unless the developer agrees to something else, the choice has already been made.
    pierovdfn said: About docs... Where do we start from?
    index.php? defaults.php? Alphabetic order?

    Well, you would know better, but I wouldn't think to start with either index.php or defaults.php specifically. Unless this is easiest for you. Alphabetical might be okay if it doesn't take long. A couple of thoughts come to mind. The first is to organize around how you think of things yourself. When you do a project, how do you think of Flatpress being organized? What do you do first? Second? A second possible organization might be to start with reference sheets you would want - to save time and effort looking things up - for one of your projects. Rather than starting at one end and exhaustively filling in every detail until the documentation is done, maybe starting with documentation for a very simple project, then adding material for more and more intricate projects. What do you think?
  • pierovdfnpierovdfn
    I think that alphabetical order is the worst: I think it's better going by logical blocks: system function, blog database etc... I think that we should analyze the FP order: defaults.php is the first file that is called. It provides some constants that are used in the whole system, then there is the file fp-includes/core/includes.php that includes all core files: we should document them first then admin panel, for me...
  • oonetoonet
    pierovdfn said: I think that alphabetical order is the wors

    Except for reference, I agree. Alphabetical is only useful when you know the name.
    pierovdfn said: I think it's better going by logical blocks: system function, blog database etc...

    Yes. The logic of the organization should help with understanding.
    pierovdfn said: I think that we should analyze the FP order: defaults.php is the first file that is called.

    The order it is called doesn't necessarily matter for someone trying to write an application. On the other hand, writing in order of execution gives an understanding of how FP works. A little unusual, perhaps, but if it makes sense to you, I think it's a great idea :-)
    pierovdfn said: we should document them first then admin panel

    Starting with defaults.php introduces system constants. Following with includes.php introduces core files. Then admin panel to configure options? Sounds good :-)
  • pierovdfnpierovdfn
    I was thinking about: 1) Constants and includes 2) System and filesystem functions 3) WP Hooks and plugin interface 4) Blog Database 5) Index.php (entries and comments) 6) Administration panel
  • oonetoonet
    It looks like I forgot to hit post. . . . This sounds fine. The only objection I can see is that the six sections are not intuitive without a fair understanding of how FP works.
  • pierovdfnpierovdfn
    I wouldn't use 6 sections... These 6 points were schematic, just to understand my idea. However now I'm working in a project and I think I won't start to make the documentation until July.
  • oonetoonet
    pierovdfn said: I wouldn't use 6 sections... These 6 points were schematic, just to understand my idea.

    Oh, okay. Those were just the areas you wanted to make sure you covered.
    pierovdfn said: However now I'm working in a project and I think I won't start to make the documentation until July.

    One project at a time :-)
  • angelus_iraangelus_ira
    Reopening the post. I would like to help, at least adding the comments on the php files. I do not know from wich files i should start or what standart for comment the files we would be using. I do not know if flatpress uses a coding guidelines but we could use at least on the comments side. If we make good comments, we can make part of the docs with phpdocs or similar (we have started to discuss this on http://flatpress.org/vanilla2/discussion/1509/php4-compatibility) but this post is a better place to talk, just like pierovdfn says. We should check who wants to work on this and share the workload.
  • pierovdfnpierovdfn
    As I said in the other post, I started to document FP but I thought nobody was interested anymore, so I stopped doing. I think it's better starting from core functions: default constants, filsystem, hooks (that, as I remember, are already documented), then the blog database and finally other features like widgets, interfacing with admin panel... I think (built in) plugins don't need to be documented and that the other plugins should be documented by their authors. It's useless documenting Smarty and I think it's already documented. Should we document also admin panels?
  • angelus_iraangelus_ira
    The admin panels shoud be document, but the priority should be low. The plugin uses the firs comments to make the table info on the admin panel, so the only thing you can document for now are the functions inside the plugin. But that should be made by the authors (there could be a coding guideline to make plugins) Smarty is documented and is an external project. None of that files should be documented. On the wiki we could add a few examples of the most used features of smarty. I have started to read the index.php of the root folder. It have a lot of functions inside. Now the question is wich order we will use to document. I prefer that you choose a work order and assing the files to the different people who want to document (for now i think you and me). I have a github repository in wich i could start to upload the files.
  • pierovdfnpierovdfn
    angelus_ira said:

    Smarty is documented and is an external project. None of that files should be documented. On the wiki we could add a few examples of the most used features of smarty.

    There are some plugins for Smarty written by NoWhereMan and put in the smarty dir.
    angelus_ira said: I have started to read the index.php of the root folder. It have a lot of functions inside.
    Now the question is wich order we will use to document. I prefer that you choose a work order and assing the files to the different people who want to document (for now i think you and me).
    I have a github repository in wich i could start to upload the files.

    I think that the order could be the parsing order of PHP.
  • angelus_iraangelus_ira
    I have forgoten the plugins inside smarty. That plugins should be documented. I think that phpdoc let you ignore files and folders so it could be config. Ok, i will document for now the index.php functions and start to add the info you have add on the other post (pastebin) to the files. Later we should said what files are working each so we do not make the same work. I will add a git repository on my github account with the modified files. (how do you make the quotes?)
  • pierovdfnpierovdfn
    I select the text and then I click quote
    • Add a Comment
    Start a New Discussion

    Howdy, Stranger!

    It looks like you're new here. If you want to get involved, click one of these buttons!

    Sign In Apply for Membership

    Categories

    In this Discussion