Loading ...
Sorry, an error occurred while loading the content.

define-help

Expand Messages
  • Bryan Schofield
    Is there a convenient way to add online help to macros? One the things about GNU Emacs is that you can easily add a little documentation right in the
    Message 1 of 4 , Feb 7, 2007
    • 0 Attachment
      Is there a convenient way to add online help to macros? One the things
      about GNU Emacs is that you can easily add a little documentation
      right in the functions. I tried define-help, but it doesn't seem to
      work as expected. I can generated a help page for a function that is
      visible through help-command, but it doesn't honor the ehf escape
      sequences.

      The example in the help page for define-help is broke. If you copy it
      to a buffer and execute-buffer, you'll get a error:
      [missing !emacro terminate]

      Change the !emacro to !ehelp and try again. This time it succeeds... sort of.

      Now try help-command paragraph-to-line. You'll see the ^[ escape
      sequence were displayed.

      Assuming define-help was working properly, it's still a very
      cumbersome way to declare help. Are there any easy ways to do it? How
      do you guys (Stephen and Jon) produce the documentation for standard
      ME macros. I don't see define-help littered through out the the
      standard emf files.
    • Phillips, Steven
      Yes there is, see the define-help command. Steve ________________________________ From: jasspa@yahoogroups.com [mailto:jasspa@yahoogroups.com] On Behalf Of
      Message 2 of 4 , Feb 7, 2007
      • 0 Attachment
        Yes there is, see the define-help command.
         
        Steve


        From: jasspa@yahoogroups.com [mailto:jasspa@yahoogroups.com] On Behalf Of Bryan Schofield
        Sent: Wednesday, February 07, 2007 4:07 PM
        To: jasspa@yahoogroups.com
        Subject: [jasspa] define-help

        Is there a convenient way to add online help to macros? One the things
        about GNU Emacs is that you can easily add a little documentation
        right in the functions. I tried define-help, but it doesn't seem to
        work as expected. I can generated a help page for a function that is
        visible through help-command, but it doesn't honor the ehf escape
        sequences.

        The example in the help page for define-help is broke. If you copy it
        to a buffer and execute-buffer, you'll get a error:
        [missing !emacro terminate]

        Change the !emacro to !ehelp and try again. This time it succeeds... sort of.

        Now try help-command paragraph-to- line. You'll see the ^[ escape
        sequence were displayed.

        Assuming define-help was working properly, it's still a very
        cumbersome way to declare help. Are there any easy ways to do it? How
        do you guys (Stephen and Jon) produce the documentation for standard
        ME macros. I don't see define-help littered through out the the
        standard emf files.

      • Phillips, Steven
        That serves me right for not reading the email! The use of !ehelp is correct so this is a doc bug. The use of escape sequences is optional but greatly help
        Message 3 of 4 , Feb 7, 2007
        • 0 Attachment
          That serves me right for not reading the email!
           
          The use of !ehelp is correct so this is a doc bug.
           
          The use of escape sequences is optional but greatly help readability of the help page and is require for links, the problem is that we can't put a real escape character into our help pages so you need to replace all the 2 character "^[" strings with a single escape character, ie. execute the following line
           
            replace-string "\\^\\[" "\x1b"
           
          Another correction though, the last link line should be:
           
                       ^[ls^[lmfill-paragraph(2)^[le.
          This will then create a good looking page.
           
          We use much more complex documentation compilers based on nroff format (all developed by Jon) but you will find that the content of me.ehf is very similar to the define-help format. One trick may be to define all your help using define-help and then execute '0 help', this will open the '*on-line help*' buffer which you can write out to your own user area as a replacement. It would need to be called me.ehf and ME does not current support a 'my.ehf' overlay feature.
           
          Steve


          From: jasspa@yahoogroups.com [mailto:jasspa@yahoogroups.com] On Behalf Of Bryan Schofield
          Sent: Wednesday, February 07, 2007 4:07 PM
          To: jasspa@yahoogroups.com
          Subject: [jasspa] define-help

          Is there a convenient way to add online help to macros? One the things
          about GNU Emacs is that you can easily add a little documentation
          right in the functions. I tried define-help, but it doesn't seem to
          work as expected. I can generated a help page for a function that is
          visible through help-command, but it doesn't honor the ehf escape
          sequences.

          The example in the help page for define-help is broke. If you copy it
          to a buffer and execute-buffer, you'll get a error:
          [missing !emacro terminate]

          Change the !emacro to !ehelp and try again. This time it succeeds... sort of.

          Now try help-command paragraph-to- line. You'll see the ^[ escape
          sequence were displayed.

          Assuming define-help was working properly, it's still a very
          cumbersome way to declare help. Are there any easy ways to do it? How
          do you guys (Stephen and Jon) produce the documentation for standard
          ME macros. I don't see define-help littered through out the the
          standard emf files.

        • Phillips, Steven
          I should also mention that one of the main reasons why we compile all the help into a separate single me.ehf file rather than embed them into the emf files is
          Message 4 of 4 , Feb 7, 2007
          • 0 Attachment
            I should also mention that one of the main reasons why we compile all the help into a separate single me.ehf file rather than embed them into the emf files is because most of the time you do not need the docs, it is far more efficient to only load them when you really need them.
             
            Steve


            From: jasspa@yahoogroups.com [mailto:jasspa@yahoogroups.com] On Behalf Of Phillips, Steven
            Sent: Wednesday, February 07, 2007 4:36 PM
            To: jasspa@yahoogroups.com
            Subject: RE: [jasspa] define-help

            That serves me right for not reading the email!
             
            The use of !ehelp is correct so this is a doc bug.
             
            The use of escape sequences is optional but greatly help readability of the help page and is require for links, the problem is that we can't put a real escape character into our help pages so you need to replace all the 2 character "^[" strings with a single escape character, ie. execute the following line
             
              replace-string "\\^\\[" "\x1b"
             
            Another correction though, the last link line should be:
             
                         ^[ls^[lmfill- paragraph( 2)^[le.
            This will then create a good looking page.
             
            We use much more complex documentation compilers based on nroff format (all developed by Jon) but you will find that the content of me.ehf is very similar to the define-help format. One trick may be to define all your help using define-help and then execute '0 help', this will open the '*on-line help*' buffer which you can write out to your own user area as a replacement. It would need to be called me.ehf and ME does not current support a 'my.ehf' overlay feature.
             
            Steve


            From: jasspa@yahoogroups. com [mailto:jasspa@ yahoogroups. com] On Behalf Of Bryan Schofield
            Sent: Wednesday, February 07, 2007 4:07 PM
            To: jasspa@yahoogroups. com
            Subject: [jasspa] define-help

            Is there a convenient way to add online help to macros? One the things
            about GNU Emacs is that you can easily add a little documentation
            right in the functions. I tried define-help, but it doesn't seem to
            work as expected. I can generated a help page for a function that is
            visible through help-command, but it doesn't honor the ehf escape
            sequences.

            The example in the help page for define-help is broke. If you copy it
            to a buffer and execute-buffer, you'll get a error:
            [missing !emacro terminate]

            Change the !emacro to !ehelp and try again. This time it succeeds... sort of.

            Now try help-command paragraph-to- line. You'll see the ^[ escape
            sequence were displayed.

            Assuming define-help was working properly, it's still a very
            cumbersome way to declare help. Are there any easy ways to do it? How
            do you guys (Stephen and Jon) produce the documentation for standard
            ME macros. I don't see define-help littered through out the the
            standard emf files.

          Your message has been successfully submitted and would be delivered to recipients shortly.