Help file needs expanding

[Lewis Rosenthal]

Now that there is a real PM help file, it needs to be fleshed out a bit more. Hopefully, some people with more experience using the editor can submit some content.

[Alfredo Fernández Díaz]

I just uploaded a first try at properly documenting (e)FTE(2).

If you open it in eFTE2, you'll see right away a few minor sections are still missing completely, but I thought I'd just publish it to get some feedback and work on any rough edges.

Enjoy!

P.S. Please don't go crazy trying to convert it to IPF, come back to me with any comments on that, or anything else ;)

[Alfredo Fernández Díaz]

eFTE2 Manual 1.0rc1

[Alfredo Fernández Díaz]

Just got rid of rc1 by overwriting with an empty file; sorry - I thought uploading rc2 would do it but 'overwrite attached files with the same name' is case sensitive :(

[Alfredo Fernández Díaz]

Just refreshed rc2 -- minor changes to text

[Alfredo Fernández Díaz]

eFTE2 Manual 1.0, only "Install: Win/Linux" missing, otherwise ready to start the reviewing process to enhance it.

[Alfredo Fernández Díaz]

I think this thing is ready now, hence v1.0

It's still not a real manual, though, but a first step in having one.

If I were to set priorities, I would say the first thing to do is review the internal commands section for accuracy and adequacy of the descriptions. After that, maybe see if more useful information can be added to the task reference (Using eFTE2 / Standard text editing). Currently it is little more than a collection of links from menu items to internal commands.

Of course, the whole tutorial / customizing section can be reviewed for usefulness, and it might be useful to add screenshots here and there (all over the manual, actually) to further illustrate some points / examples.

Currently I have two versions: the main one in HTML, and the OS/2-specific IPF source. I hope better conversion tools appear the future -- the energy to code something adequate seems way beyond what is foreseeably needed to keep these two in synch, and right now I don't think I will be partaking in enough projects to justify creating it.

You'll find this note in the IPF file:

---

.*
.* eFTE2 user and reference manual -- mrwarper's note to future maintainers
.*
.* This file is adapted from the main HTML documentation and its contents should
.* be synchronized with that after it is updated. So far, both files need to be
.* maintained separately due to lack of appropriate tools.
.*
.* In short, for the manual to be as useful as possible, a number of elements
.* must be linked to one another. While this can be done freely with HTML
.* elements, limitations of IPFC impose that some contents of the document
.* must be duplicate in the IPF source:
.*
.* Single text elements within their section can't be linked to individually, so
.* they are duplicated instead as footnotes (which must also include many 'see
.* also' links). Such notes (most notably reference for individual editing
.* commands and mode settings) have been placed at the end of the section the
.* text they mirror belongs to, and they remain invisible (duplication happens
.* only in the source but not in rendering) until links to them are selected --
.* then they pop up in the right place.
.*
.* They should be locatable searching *in reverse* for ":fn id=" from header tags
.* :h1-:h6, since these separate sections.
.*
.* In the event that you need to add or modify anything in this file, please
.* take a few extra seconds to repeat that work in the footnotes to make this
.* a quality manual.
.*

[Alfredo Fernández Díaz]

ePub version of the manual -- an example of other useful formats that can be generated automatically. PDF comes out nice but is too heavy (600Kb).

[Gregg Young]

What tools have you tried to convert to ipf? I can see how Viper help does if you haven't tried it. I will review this. Thanks

[Alfredo Fernández Díaz]

Unless I totally missed a chapter in the docs, the VyperHelp I have (v1.11) can output HTML but not import it or convert to IPF.

As we commented via mail, I tried Zabolotny's HTML2IPF (with later additions by Ulrich Möller and Steve Levine), and H2I from the xwphelpers, and a bunch of older converters. All of them expect proprietary or 'tag soup' HTML or are otherwise terribly outdated.

In the end it was best to convert it 'manually' in FTE. I use 100% clean markup so actually it took me way longer to refresh my knowledge of IPF and rewrite the mode (soon to be re-released) and add real macros.

It shouldn't be much of a hassle to modify / add bits of info here and there in two docs instead of one. It would of course be nice to have a good converter and revert to maintaining a single HTML source in the future, though, so I'm all ears about this.