summaryrefslogtreecommitdiffhomepage
diff options
context:
space:
mode:
-rw-r--r--contributing.org78
-rw-r--r--doc/write-your-own-plugin.org74
-rw-r--r--readme.org6
3 files changed, 84 insertions, 74 deletions
diff --git a/contributing.org b/contributing.org
index 41c2af1..14bce0d 100644
--- a/contributing.org
+++ b/contributing.org
@@ -19,9 +19,10 @@ this case please don't merge any branches, but actually rebase! This is
a very nifty feature that =git= offers in order to remain a clean
history.
-Give your commits descriptive names! Further, it's also highly recommended to
-add a description of /why/ you made a certain change. The syntax for this is
-*commit message*, blank line, *more description*. For example:
+Give your commits descriptive names! Further, it's also highly
+recommended to add a description of /why/ you made a certain change.
+The syntax for this is *commit message*, blank line, *more description*.
+For example:
#+begin_src shell
Commit Message (max. 50 characters)
@@ -48,72 +49,5 @@ request:
Please also remember to update the =changelog.md= file, as well as any
other documentation that your pull request touches upon. For example,
-if you add a new plugin you should update the [[./doc/plugins.org][plugins documentation]].
-
-* Writing Your Own Plugin
-
-Writing a plugin for xmobar is very simple!
-
-First, you need to create a data type with at least one constructor.
-Next you must declare this data type an instance of the =Exec= class, by
-defining the one needed method (alternatively =start= or =run=) and 3
-optional ones (=alias=, =rate=, and =trigger=):
-
-#+begin_src haskell
- start :: e -> (String -> IO ()) -> IO ()
- run :: e -> IO String
- rate :: e -> Int
- alias :: e -> String
- trigger :: e -> (Maybe SignalType -> IO ()) -> IO ()
-#+end_src
-
-=start= must receive a callback to be used to display the =String=
-produced by the plugin. This method can be used for plugins that need to
-perform asynchronous actions. See =src/Xmobar/Plugins/PipeReader.hs= for
-an example.
-
-=run= can be used for simpler plugins. If you define only =run= the
-plugin will be run every second. To overwrite this default you just need
-to implement =rate=, which must return the number of tenth of seconds
-between every successive runs. See [[https://github.com/jaor/xmobar/blob/master/examples/xmobar.hs][examples/xmobar.hs]] for an example of
-a plugin that runs just once, and [[https://github.com/jaor/xmobar/blob/master/src/Xmobar/Plugins/Date.hs][src/Xmobar/Plugins/Date.hs]] for one
-that implements =rate=.
-
-Notice that Date could be implemented as:
-
-#+begin_src haskell
- instance Exec Date where
- alias (Date _ a _) = a
- start (Date f _ r) = date f r
-
- date :: String -> Int -> (String -> IO ()) -> IO ()
- date format r callback = do go
- where go = do
- t <- toCalendarTime =<< getClockTime
- callback $ formatCalendarTime defaultTimeLocale format t
- tenthSeconds r >> go
-#+end_src
-
-This implementation is equivalent to the one you can read in
-=Plugins/Date.hs=.
-
-=alias= is the name to be used in the output template. Default alias
-will be the data type constructor.
-
-After that your type constructor can be used as an argument for the
-Runnable type constructor =Run= in the =commands= list of the
-configuration options.
-
-** Using a Plugin
-
-To use your new plugin, you need to use a pure Haskell configuration for
-xmobar, and load your definitions there. You can see an example in
-[[./examples/xmobar.hs][examples/xmobar.hs]] showing you how to write a Haskell configuration that
-uses a new plugin, all in one file.
-
-When xmobar runs with the full path to that Haskell file as its argument
-(or if you put it in =~/.config/xmobar/xmobar.hs=), and with the xmobar
-library installed (e.g., with =cabal install --lib xmobar=), the Haskell
-code will be compiled as needed, and the new executable spawned for you.
-
-That's it!
+if you add a new plugin (see [[./doc/write-your-own-plugin.org][here]] for more information) you should
+update the [[./doc/plugins.org][plugins documentation]].
diff --git a/doc/write-your-own-plugin.org b/doc/write-your-own-plugin.org
new file mode 100644
index 0000000..2645c3b
--- /dev/null
+++ b/doc/write-your-own-plugin.org
@@ -0,0 +1,74 @@
+* Writing Your Own Plugin
+
+Writing a plugin for xmobar is very simple!
+
+First, you need to create a data type with at least one constructor.
+Next you must declare this data type an instance of the =Exec= class, by
+defining the one needed method (alternatively =start= or =run=) and 3
+optional ones (=alias=, =rate=, and =trigger=):
+
+#+begin_src haskell
+ start :: e -> (String -> IO ()) -> IO ()
+ run :: e -> IO String
+ rate :: e -> Int
+ alias :: e -> String
+ trigger :: e -> (Maybe SignalType -> IO ()) -> IO ()
+#+end_src
+
+=start= must receive a callback to be used to display the =String=
+produced by the plugin. This method can be used for plugins that need to
+perform asynchronous actions. See =src/Xmobar/Plugins/PipeReader.hs= for
+an example.
+
+=run= can be used for simpler plugins. If you define only =run= the
+plugin will be run every second. To overwrite this default you just need
+to implement =rate=, which must return the number of tenth of seconds
+between every successive runs. See [[https://github.com/jaor/xmobar/blob/master/examples/xmobar.hs][examples/xmobar.hs]] for an example of
+a plugin that runs just once, and [[https://github.com/jaor/xmobar/blob/master/src/Xmobar/Plugins/Date.hs][src/Xmobar/Plugins/Date.hs]] for one
+that implements =rate=.
+
+Notice that Date could be implemented as:
+
+#+begin_src haskell
+ instance Exec Date where
+ alias (Date _ a _) = a
+ start (Date f _ r) = date f r
+
+ date :: String -> Int -> (String -> IO ()) -> IO ()
+ date format r callback = do go
+ where go = do
+ t <- toCalendarTime =<< getClockTime
+ callback $ formatCalendarTime defaultTimeLocale format t
+ tenthSeconds r >> go
+#+end_src
+
+Modulo some technicalities like refreshing the time-zone in a clever
+way, this implementation is equivalent to the one you can read in
+=Plugins/Date.hs=.
+
+=alias= is the name to be used in the output template. Default alias
+will be the data type constructor.
+
+After that your type constructor can be used as an argument for the
+Runnable type constructor =Run= in the =commands= list of the
+configuration options.
+
+If your plugin only implements =alias= and =start=, then it is advisable
+to put it into the =Xmobar/Plugins/Monitors= directory and use one of
+the many =run*= functions in [[../src/Xmobar/Plugins/Monitors/Common/Run.hs][Xmobar.Plugins.Monitors.Run]] in order to
+define =start=. The =Exec= instance should then live in
+[[../src/Xmobar/Plugins/Monitors.hs][Xmobar.Plugins.Monitors]].
+
+** Using a Plugin
+
+To use your new plugin, you need to use a pure Haskell configuration for
+xmobar, and load your definitions there. You can see an example in
+[[../examples/xmobar.hs][examples/xmobar.hs]] showing you how to write a Haskell configuration that
+uses a new plugin, all in one file.
+
+When xmobar runs with the full path to that Haskell file as its argument
+(or if you put it in =~/.config/xmobar/xmobar.hs=), and with the xmobar
+library installed (e.g., with =cabal install --lib xmobar=), the Haskell
+code will be compiled as needed, and the new executable spawned for you.
+
+That's it!
diff --git a/readme.org b/readme.org
index 159c8da..3093d5e 100644
--- a/readme.org
+++ b/readme.org
@@ -209,8 +209,10 @@ Since 0.14 xmobar reacts to SIGUSR1 and SIGUSR2:
- If you want to jump straight into configuring xmobar, head over to the
[[./doc/quick-start.org][quick-start]] guide.
-- If you want to know how to write your own plugin, or how to contribute
- to the xmobar project, check out [[contributing.org][contributing]].
+- If you want to know how to contribute to the xmobar project, check out
+ [[contributing.org][contributing]].
+
+- If you want to write your own plugins, see [[./doc/write-your-own-plugin.org][write-your-own-plugin]].
* Authors and credits