tricks/blojsom2drupal/README.txt

blojsom2drupal
==============

Copyright 2006 openDemocracy (http://www.opendemocracy.net)

ABOUT
-----

blojsom2drupal is a command-line tool written in PHP for importing
Blojsom blog data into Drupal.

*** IMPORTANT NOTES ***

1) This module was used specifically for Blojsom v2.29 which stores
all it's content in files. Newer versions use a database.

2) As it currently stands, there is some special-case code in there for
guessing the names of authors of anonymous posts. This code is pretty
specific to openDemocracy, and may or may not be useful to other users.
The offending code is in _blojsom2drupal_resolve_post_author() and
can be commented out easily enough.


USAGE
-----

blojsom2drupal includes drupal code, and so assumes that the current
directory is the main drupal directory.

 blojsom2drupal.php [options]

The options are:

-h help

-v verbose
  displays info about each post as it is imported 

-a list authors and exit
  Print out a list of all the author names found in the blojsom data,
  one per line (useful as a basis for a user remap file)
  No further processing is done.

-l list categories and exit
  Print out all the blojsom categories found.
  Useful for building a cetegory remap file.
  No further processing is done.

-d dry run (don't write anything into drupal)
  Performs all actions except actually writing into the drupal
  database.

-u <remapfile> use file to remap usernames
  The remap file is used to map usernames found in the blojsom data
  to usernames in drupal. Without any remapping, it's assumed that
  drupal has users of the same names as in blojsom.
  The remap file consists of lines of the form:
    <blojsom username>:<drupal username>
  Either username can be empty. eg blojsom posts without authors can
  be attributed to a catch-all drupal user.
  Comments are denoted with '#'.

-c <remapfile> use file to remap categories
  The remap file is used to map categories in the blojsom data
  to taxonomy terms in drupal.
  Without any remapping, it's assumed that drupal has taxonomy terms
  of the same names as the blojsom categories.
  The remap file consists of lines of the form:
    <blojsom category>:<drupal category>
  Comments are denoted with "#".

-t <term(s)> taxonomy terms to apply to all imported posts
  Multiple terms can be specified by separating them with commas.
  All imported posts will have these terms applied, in addition
  to whatever terms are derived from the original blojsom categories.
  (unlike the categories, the -t terms are not subject to the remap
  file).

-f <srcdir> blojsom forum to import (required unless -a or -l used)
  Path to the root directory of the source blojsom forum

The import process does not create any users or taxonomy terms in drupal.
If a user or term is encountered (after any possible remapping) which
cannot be found in drupal, the import process stops with an error message.

So in general, it pays to make sure the import works using the dry run
option (-d) first. Also make a backup of your database too, just in
case :-)

The -a and -l options can be used to obtain a list of all the usernames
or taxonomy terms expected, and is a good starting point for writing
remapping files.


EXAMPLES
--------

commandline:

  $ cd <main_drupal_directory>
  $ blojsom2drupal.php -f ./blojsom-blogs/fruit_talk -u usermap -c catmap -t "Fruit Talk"

usermap file:

  # someone accidentally mis-spelt their name - merge into one user
  Bubba Joe-Bob:bubba
  Bubba Jo-Bob:bubba

  # map anonymous posts to 'fruitfan' user
  :fruitfan

catmap file:

  # Not many grapefruit ethusiasts - merge categories
  Lemon Talk:Citrus Scene
  Grapefruit Talk:Citrus Scene
  # all other categories have same name in drupal


AUTHOR
-------

Ben Campbell (http://www.scumways.com)
Email address can be found at the above homepage!

Comments/feedback welcome!

1	blojsom2drupal
2	==============
3
4	Copyright 2006 openDemocracy (http://www.opendemocracy.net)
5
6	ABOUT
7	-----
8
9	blojsom2drupal is a command-line tool written in PHP for importing
10	Blojsom blog data into Drupal.
11
12	* IMPORTANT NOTES *
13
14	1) This module was used specifically for Blojsom v2.29 which stores
15	all it's content in files. Newer versions use a database.
16
17	2) As it currently stands, there is some special-case code in there for
18	guessing the names of authors of anonymous posts. This code is pretty
19	specific to openDemocracy, and may or may not be useful to other users.
20	The offending code is in _blojsom2drupal_resolve_post_author() and
21	can be commented out easily enough.
22
23
24	USAGE
25	-----
26
27	blojsom2drupal includes drupal code, and so assumes that the current
28	directory is the main drupal directory.
29
30	blojsom2drupal.php [options]
31
32	The options are:
33
34	-h help
35
36	-v verbose
37	displays info about each post as it is imported
38
39	-a list authors and exit
40	Print out a list of all the author names found in the blojsom data,
41	one per line (useful as a basis for a user remap file)
42	No further processing is done.
43
44	-l list categories and exit
45	Print out all the blojsom categories found.
46	Useful for building a cetegory remap file.
47	No further processing is done.
48
49	-d dry run (don't write anything into drupal)
50	Performs all actions except actually writing into the drupal
51	database.
52
53	-u <remapfile> use file to remap usernames
54	The remap file is used to map usernames found in the blojsom data
55	to usernames in drupal. Without any remapping, it's assumed that
56	drupal has users of the same names as in blojsom.
57	The remap file consists of lines of the form:
58	<blojsom username>:<drupal username>
59	Either username can be empty. eg blojsom posts without authors can
60	be attributed to a catch-all drupal user.
61	Comments are denoted with '#'.
62
63	-c <remapfile> use file to remap categories
64	The remap file is used to map categories in the blojsom data
65	to taxonomy terms in drupal.
66	Without any remapping, it's assumed that drupal has taxonomy terms
67	of the same names as the blojsom categories.
68	The remap file consists of lines of the form:
69	<blojsom category>:<drupal category>
70	Comments are denoted with "#".
71
72	-t <term(s)> taxonomy terms to apply to all imported posts
73	Multiple terms can be specified by separating them with commas.
74	All imported posts will have these terms applied, in addition
75	to whatever terms are derived from the original blojsom categories.
76	(unlike the categories, the -t terms are not subject to the remap
77	file).
78
79	-f <srcdir> blojsom forum to import (required unless -a or -l used)
80	Path to the root directory of the source blojsom forum
81
82	The import process does not create any users or taxonomy terms in drupal.
83	If a user or term is encountered (after any possible remapping) which
84	cannot be found in drupal, the import process stops with an error message.
85
86	So in general, it pays to make sure the import works using the dry run
87	option (-d) first. Also make a backup of your database too, just in
88	case :-)
89
90	The -a and -l options can be used to obtain a list of all the usernames
91	or taxonomy terms expected, and is a good starting point for writing
92	remapping files.
93
94
95	EXAMPLES
96	--------
97
98	commandline:
99
100	$ cd <main_drupal_directory>
101	$ blojsom2drupal.php -f ./blojsom-blogs/fruit_talk -u usermap -c catmap -t "Fruit Talk"
102
103	usermap file:
104
105	# someone accidentally mis-spelt their name - merge into one user
106	Bubba Joe-Bob:bubba
107	Bubba Jo-Bob:bubba
108
109	# map anonymous posts to 'fruitfan' user
110	:fruitfan
111
112	catmap file:
113
114	# Not many grapefruit ethusiasts - merge categories
115	Lemon Talk:Citrus Scene
116	Grapefruit Talk:Citrus Scene
117	# all other categories have same name in drupal
118
119
120	AUTHOR
121	-------
122
123	Ben Campbell (http://www.scumways.com)
124	Email address can be found at the above homepage!
125
126	Comments/feedback welcome!
127